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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed world), and the description adds real value beyond them: the data is compiled from public specifications and is not a supplier's guaranteed certificate of analysis, the gap analysis is anchored to N550 only, and only one grade is returned per call. It stops short of describing failure behavior when an id or name matches nothing.

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 Purpose / Guidelines / Scope / Limits / Ex structure is front-loaded and skimmable, with an explicit example block that removes ambiguity. It is on the verbose side for a single-lookup tool, but nearly every clause carries distinct information (record contents, lookup keys, sibling routing, data provenance).

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?

An output schema exists, so return-value detail is not needed, and the description covers the remaining agent-critical questions: what fields the full record holds, which keys to use, which sibling to pick instead, and what the data's limits are. Nothing needed 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?

Schema coverage is 100%, so the baseline is 3, but the description goes further by clarifying that id and name are alternatives (schema does not state '二选一' semantics as prominently), giving example values for each, and showing an actual call shape combining name with response_format. Marginals add meaning beyond the schema text.

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?

Specific verb+resource ('fetch one carbon black grade in full') with an explicit inventory of what the record contains (ASTM parameters, application list, process route, brand owner, rCB gap analysis). It directly distinguishes itself from the closest sibling by stating that get_grade_spec returns only the bare ASTM parameter table.

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?

Names both lookup keys (semantic id or grade name) with concrete examples, routes the agent to query_grades for discovery and get_grade_spec for spec-only needs, and states the explicit exclusion: 'For a bare ASTM parameter table only, use get_grade_spec instead.' A Limits block adds scope caveats, so there is essentially no inference left.

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