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

Annotations already indicate readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds significant behavioral context: facets return only slugs that actually appear on the graph, include counts, and are sorted by count descending. It also explains the scope parameter's effect on which labels are included. This goes well beyond the annotations, providing essential behavior details for an agent.

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: it starts with the main purpose, then explains facets, gives usage guidance, and finally details the parameter and return value. It is informative but not overly verbose. Minor improvement could be made by trimming the explanation of facets (e.g., 'Facets are taxonomy categories...') to be more concise. Still, it is effective and front-loaded.

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 single optional parameter, detailed annotations, and the presence of an output schema (though not provided), the description is remarkably complete. It explains the parameter constraints, the return structure (JSON with 'meta' and 'facets', each facet including name, applies_to, and values), and the sorting. The only minor omission is the content of 'meta', but it is not critical for the agent's use. The description fully equips the agent to invoke the tool 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 has a single optional parameter 'scope' with no description or enum constraints (schema description coverage 0%). The description fully compensates by enumerating the valid values: 'clause', 'guide', 'all', explaining what each means, and noting the default. This adds crucial meaning that the schema alone fails to provide, enabling correct invocation.

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 the tool's purpose: 'List taxonomy facets and their value slugs across TCLP content.' It provides concrete examples of facets (sector, practice_area, etc.) and mentions counts. It also distinguishes from the sibling tool taxonomy_content by advising to use this first and then call taxonomy_content with chosen slugs. The verb 'list' and resource 'taxonomy facets and value slugs' are specific and unambiguous.

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 explicitly explains when to use this tool: 'Use this to discover the vocabulary, then call taxonomy_content with chosen slugs.' This directly tells the agent to use taxonomy_facets first to obtain valid slugs before using taxonomy_content. It does not mention entity_lookup or search, but the guidance is clear and sufficient for selecting the correct tool in a workflow.

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