discover

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare a safe read; the description goes well beyond them by disclosing result cardinality (up to 8), ranking order (most trusted first), result contents (exact names plus inputs, with '?' marking optional), and the existence of RECIPES as read-only prior art. That is substantive behavioral context an agent could not get from the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The entry-point instruction is front-loaded in two words, and each sentence carries a distinct obligation (search, don't refuse, what comes back, how to treat recipes). The long enumeration of domains is justified as retrieval priming but does make the middle sentence heavy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description fully covers the return shape: count limit, ordering, tool names, input signature with optionality marker, and recipe objects. Nothing an agent needs to invoke it or interpret results is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single 'goal' parameter has no schema description, but the text compensates by instructing the agent to phrase it 'with the person's own words', which is real guidance about query formulation rather than a restatement of the field. It stops short of stating length, language, or whether multiple intents can be packed in.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action (search the unlisted tools on this computer) and explicitly frames itself as the entry point with 'START HERE'. It also draws a boundary against siblings by naming readiness for counting and describe for reading recipes, so an agent can place it in the toolset without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit trigger ('BEFORE you ever say Fieldkit cannot do something') and two explicit alternative routes: call readiness to count the tools, use describe to read a recipe. It also states recipes are 'never to run', which is a clear prohibition rather than an omission.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.