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

Annotations only declare readOnly/openWorld/destructive, so the description carries the behavioral load and does so richly: returns metadata only, never source; results carry modules with exported names and first comment line; own hits are ranked first and marked own:true; forgeId can narrow either corpus or cause a refusal if both switches are off; and a prompt-injection warning about user-authored titles/summaries/tags. This is far beyond what the annotations provide.

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?

Purpose and the source-vs-metadata distinction are front-loaded, and each sentence conveys distinct operational detail. It is dense and long for a single paragraph, but almost no sentence is redundant, so it avoids a lower score.

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, five parameters, and low schema coverage, the description fills the gaps: it describes the return shape (metadata, modules with exported names and comment line), the ranking/own marking, scoping rules, refusal conditions, and the safety caveat. Nothing essential for correct invocation appears 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 only 20% (just forgeId), so the description must compensate and largely does: it explains query's omit-to-list behavior, forgeId's scoping semantics, and vendorable's default-true widen-to-non-copyable behavior, plus references tags indirectly. Only limit is left unexplained, keeping it short of a 5.

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 and resource ('Search published public forges to use as reference') and clarifies the nature of the content ('real, working examples of how similar geometry is structured and parameterized'). It also differentiates itself from siblings by naming read_reference_part as the follow-up for source. An agent can distinguish it from list_forges and search_part_files without opening any 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?

Explicitly covers when to omit query ('Omit query to list everything'), what happens without forgeId versus with forgeId, and when to pass vendorable:false. It names the follow-up tool (read_reference_part) and the scoping alternative, leaving little to inference.

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