Designing Good Tools

A tool the model can't understand is a tool the model won't use — or worse, will use wrongly. The model chooses which tool to call, and with what arguments, based entirely on the names, descriptions, and schemas you give it. Tool design is therefore prompt engineering in a structured costume: every word counts.

Name and describe for the reader (the model)

Treat each tool's metadata as documentation written for a smart colleague who has never seen your codebase:

• Use clear, specific names. getStudentEnrollment beats query2. The name alone should hint at what the tool does and when to reach for it.
• Write descriptions that disambiguate. If you have both searchLessons and getLessonById, each description must say when to use it — "search by keyword when you don't have an ID" versus "fetch one lesson when you already know its ID." Most wrong-tool errors trace back to vague, overlapping descriptions.
• State the cost or side effects. "Sends an email to the student — only call after explicit confirmation" steers the model away from firing irreversible actions casually.

Define parameters with strict schemas

Each tool's parameters are a JSON schema, and the model fills it in. Make the schema do the work:

1. Type everything precisely — integer, string, enum for fixed choices. An enum of ["active", "withdrawn", "completed"] is far safer than a free-text status.
2. Mark required vs. optional fields so the model knows what it must supply.
3. Describe each field, including units and format: "dueDate: ISO-8601 date, e.g. 2026-09-01". The model reads these descriptions when populating arguments.
4. Keep parameters minimal. Fewer, well-named fields mean fewer chances to get it wrong.

In .NET with Semantic Kernel, you express this with [KernelFunction] and [Description] attributes on a C# method and its parameters; the framework generates the JSON schema the model sees. Your method signature is the contract.

Keep tools small and composable

Prefer several focused tools over one do-everything tool with a mode flag. A small tool is easier for the model to choose correctly, easier for you to validate, and easier to test. One tool, one job. And don't overwhelm the model — a handful of relevant, well-described tools outperforms thirty vaguely-named ones, because every extra tool is another chance to pick wrong.

A useful gut check: read only your tool names and descriptions, with no other context. If you can't tell which tool fits a given request, the model can't either. LyraLearn's content-ingestion tools — fetchSourceDocument, chunkAndEmbed, upsertKnowledge — pass that test: each name and description maps to exactly one step, so the model never has to guess.