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

Annotations already declare readOnly, idempotent and non-destructive, so the description earns credit for what it adds: 'Public: needs no credential' and the fact that this only publishes catalogue metadata rather than executing anything. The note that run_reference_pipeline returns 501 pipeline_execution_unavailable instead of a simulated price is a genuinely useful anti-hallucination guard. Minor gap: no statement about size/limits of the returned catalogue or whether results can change over time.

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?

Front-loaded with purpose in the opening clause, then alternatives, then the public/no-key note — a sensible order. The first sentence is a long run-on enumeration and the 501 detail about a sibling tool is slightly more than strictly needed, but no sentence is filler.

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 input schema to speak of and no output schema, the description carries the return shape entirely and does so field by field, while also covering auth (public, no credential), read-only semantics and sibling routing. Nothing an agent needs in order to call it correctly 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 tool takes no parameters, so the baseline of 4 applies. The description correctly implies an unfiltered full listing with nothing to configure, matching the empty object schema.

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 ('see the multi-step pricing pipelines ... and the stages') and then enumerates exactly what each record carries: name, purpose, topology, latency/cost ceilings, consent, trust zones, plus a stage catalogue with layer and tags. That detail distinguishes it unambiguously from run_reference_pipeline, compute_price and price_from_capture in the same namespace.

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 routes to alternatives with conditions: run_reference_pipeline to execute (with the caveat that it 501s until switched on), price_from_capture for photo input, compute_price for numeric input, run_pricing_chain for custom chains. Both the 'use this when' and 'use something else when' sides are covered.

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