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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds behavioral detail by explaining what data is returned and how the 'detail' parameter changes scope (full source metadata vs. summary). It also discloses that it returns a list of sources with versions and licenses—useful context beyond the schema. No contradictions with annotations.

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 well-structured: a clear opening sentence, a detailed enumeration of outputs, a list of integrated sources, and concluding use cases. It is informative without being verbose, and the key purpose is front-loaded. Slightly long but every sentence adds value, so it remains appropriately sized.

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 a single optional boolean parameter and a clear output schema (present), the description covers what the tool returns, why it should be used, and the context of data currency. It does not describe exact response formatting, but that is handled by the output schema. For this simple, read-only metadata tool, the description is sufficiently complete for an agent to select and call it 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 single parameter 'detail' is fully described in the input schema (coverage 100%), including its boolean semantics and default. The tool description does not add extra meaning to the parameter itself; it only provides examples of output content. Since the schema already carries the load, a baseline of 3 is appropriate.

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 clearly states a specific verb ('Retrieve') and resource ('build metadata and data source statistics') for the MyChem.info API. It enumerates the exact outputs (build version, date, record count, source list), and it is obviously distinct from sibling tools like mychem.chemicals.annotation or mychem.chemicals.search which perform different operations. An agent can immediately understand what this tool does and why it exists.

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 provides explicit use cases: 'verify data currency before large annotation jobs' and 'cite specific source versions in research publications.' This clearly signals when to invoke this tool. It does not explicitly state when not to use it, but the context and sibling names (e.g., annotation, batch_query, search) imply this is only for metadata, not for chemical queries. The guidance is direct and actionable.

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