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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description still adds real behavioral context beyond them: state lives in the conversation rather than on the server, no requests are sent, the certificate route never queries a lab database, and 'FL' is preserved rather than substituted with 'IF'.

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?

It is compact, and the route definitions come first, but it is delivered as a single run-on block of telegraphic clauses ('FL is preserved and never substituted with IF.'). Some content is redundant, e.g. the certificate route's 'without accessing a lab database' restated by the closing 'No requests are sent.'

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 stateful, nested-schema tool with no output schema, the description covers the return shape, state ownership, scope boundaries, and the handoff to estimate_rapaport. It does not say how to reset or overwrite an existing state, what happens when route_id conflicts with the carried state, or how it relates to siblings knowledge_search and knowledge_topic.

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 top-level schema has no descriptions (0% coverage), so the description must carry the load. It defines what each route_id enum value means and instructs that state holds only confirmed values with deferred fields tracking unanswered questions, which is exactly the semantics an agent needs. It does not explain the nested reasons/values duplication or how state should be shaped on the first call, leaving some gaps.

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 enumerates the four routes with a concrete gloss for each (choose = stone selection, offer = seller price review, certificate = report and stone-matching checklist, value = appraisal of an owned stone) and states the return payload: next question, current summary, steps, and expert handoff. Combined with the route list, an agent can tell what this tool does and how it differs from calculate/query siblings.

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?

It gives explicit routing rules: use estimate_rapaport only when calculation.ready is true, pass only user-provided or confirmed values (suggestions are not choices), deferred questions stay unresolved, and unrelated origins/shapes get scope_review on the three selection routes. The certificate route's exclusions (no lab database, no stone inspection, no Rapaport calculation) tell the agent when to pick a different tool.

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