Terminology Versions

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

Annotations already declare readOnly/openWorld/idempotent safely. The description adds meaningful context: it identifies the bundled CID-10 as frozen at V2008, notes the ICD-10 → ICD-11 transition tables are currently 2025-01, and clarifies that the ICD-10 → ICD-11 version is read live while other entries are project-release metadata. This goes beyond annotations and helps the agent anticipate dynamic vs. static 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 front-loaded with the core purpose, then uses compact bullet-style use cases that are directly actionable. Every sentence earns its place; there is no filler, redundant phrasing, or repetition of schema details already present.

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?

Given the tool has a single optional parameter, an output schema, and clear annotations, the description covers all necessary context: purpose, use cases, data provenance, default behavior, and the distinction between live and bundled metadata. It is fully self-contained for an agent to select and invoke correctly.

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 input schema already has 100% coverage with an enum and description for the single optional parameter. The description reinforces behavior by stating filtering yields a single entry and omitting returns all 8, adding the concrete count and default semantics. This is a small but real enhancement over the schema alone.

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?

Description opens with a specific verb and resource: 'List the current version, release date, publisher, source URL, and update cadence of every terminology...' This clearly identifies the tool's output and scope. It also inherently distinguishes itself from sibling search/lookup/mapping tools by focusing on version metadata rather than content operations.

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?

The description gives explicit use cases ('Useful for pipeline maintainers who need to...') and clear filtering instructions ('Pass `terminology` to filter... otherwise the full set of 8 is returned'). It does not explicitly state when not to use this tool in favor of alternatives, but the use-case framing provides strong contextual guidance.

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