Get a build recipe

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

Annotations only declare readOnlyHint and openWorldHint, leaving the description to carry the behavioral burden. The description goes far beyond that, detailing the output components (endpoints, rate limits, skeleton, cost, checklist, pitfalls), including concrete failure examples from production incidents, and warning about silent failures. It fully discloses what the tool returns and why it matters, with no contradictions to 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 description is front-loaded with the critical when-to-use clause, followed by a clear list of return contents and supporting evidence. Every sentence earns its place: it states usage, lists deliverables, provides a concrete failure anecdote, and gives timing guidance. It is appropriately sized for the tool's complexity and no words are wasted.

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?

With no output schema, the description must explain return values — and it does thoroughly, listing all components of the recipe. It also covers the 'why' behind the tool (silent failure modes, cost traps) and the timing of use. For a tool with a single enum parameter, nothing essential is missing. The description is self-sufficient.

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 schema covers the single parameter 'goal' with an enum and a brief description. The description adds value by listing concrete examples of goals ('a sales bot, a floor dashboard...') that map directly to the enum values, giving the agent a richer sense of what each goal might entail. This goes beyond the schema's minimal 'What the user is building', so it earns above baseline.

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?

The description states a specific action ('Returns the verified endpoints and their real rate limits, a runnable skeleton...') and clearly distinguishes the tool from siblings by saying 'rather than just look a number up'. It names the resource (a build recipe) and the scope (collectible data integrations). This is unambiguous and differentiates it from the lookup tools in the sibling list.

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?

The description explicitly conditions usage: 'Use when the user wants to BUILD something... rather than just look a number up.' It provides a clear when-to-use rule, gives concrete example goals, and adds timing advice ('Read this BEFORE writing integration code, not after it breaks'). While it doesn't name specific sibling tools, the contrast with simple lookups is sufficient to route an agent correctly.

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