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

Annotations already establish read-only, non-destructive, open-world behavior, and the description adds meaningful constraints beyond them: it cannot place orders or take payments, cannot guarantee zero alcohol, and one claim 'does not establish that no other records or sources exist'. It also flags that declarations like 'Below 0.5%' do not prove measurement or lab testing — useful epistemic limits on the returned data.

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 bloated with repeated refusal policy that largely duplicates the domain scope across sentences, and it is not front-loaded — the actual tool purpose appears about two-thirds of the way through. Several sentences ('Do not invent a product or producer') restate the same non-fabrication point.

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?

For a single-uid read tool with no output schema and only annotations for safety, the description covers the return shape (provenance.sources, version history), the source-attribution requirement, and the limits of what one claim proves. The main gap is that the refusal policy crowds out any concrete detail on the single input parameter.

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?

With a single parameter and 0% schema description coverage, the schema supplies only a minLength on claim_uid. The description compensates partially by telling the agent where the value comes from ('Copy claim_uid from a profile or claim search'), implying it is an opaque identifier, but adds nothing about format, case, or failure behavior on a bad uid.

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 does contain a specific verb+resource — 'Retrieve a published claim with provenance.sources and version history' — but this arrives only after six sentences of domain-scope and refusal policy. Differentiation from siblings is only implicit, via 'Copy claim_uid from a profile or claim search' and 'Use this to check a source behind a profile claim preview', which gestures at search_claims but never names the routing rule.

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?

Offers concrete when-not-to-use guidance: decline excluded-category recommendations, purchasing requests, and catalogue-wide zero-alcohol guarantees 'without a lookup', and explicitly warns that 'an empty search is not how to establish this exclusion'. That is real invocation guidance, but it never directly contrasts get_claim with get_beverage, get_entity, or search_claims for the same lookup.

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