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

Annotations already cover readOnly, idempotent and closed-world, but the description adds real behavioral context: reads only this server's catalog with no network or side effects, unknown ids return a did-you-mean suggestion, and filters can't be combined with the wrong argument. It stops short of describing result size or pagination for the no-argument catalog dump.

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?

Extremely dense but front-loaded: purpose first, then per-mode semantics, then routing advice and edge cases. Every sentence carries information, though the long running sentences make it slightly harder to scan than it could be.

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?

Covers all three modes, their outputs at a conceptual level, argument precedence, filter interaction, failure behavior, and the bulk alternative. Since an output schema exists, return-value detail is correctly omitted, leaving nothing an agent needs 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?

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining what each mode yields (query is ranked and led by solved_before recipes with success rates; op returns the full contract with args schema and examples; recipe returns steps, params and track record) and how accepts combines with query.

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 verb (find/read) plus resource (op or recipe) and enumerates the three lookup modes with what each returns. It also explicitly distinguishes itself from run_op/run_pipeline and the front-door read tools, so an agent can place it 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 explicit when-to-use ('Call this before run_op or run_pipeline when you don't know the op id or its args'), when-not ('skip it for jobs the front-door tools ... already cover'), and an alternative for bulk reading (the extcord://catalog resource). Argument precedence (op wins, then recipe) is also spelled out.

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