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

The annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, so the agent knows this is a non-destructive, read-only operation. The description adds important behavioral context about the API key requirement: it notes that Pipeworx fronts the key and that passing _apiKey uses a personal key. This is beyond what annotations provide and helps the agent understand authentication nuances. It also clarifies the return type (headings and titles, not full text), which is a behavioral detail. One minor gap is that it doesn't mention rate limits or error handling, but given the strong annotation coverage, this is acceptable; a 4 is justified.

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 three sentences long and each sentence earns its place: the first states the purpose and return type, the second covers the key requirement and return details, the third directs to an alternative. It is front-loaded with the core purpose, and there is no fluff. It is concise and structured for quick scanning by an agent.

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 tool with 2 parameters, 100% schema coverage, no output schema, and strong annotations, the description is complete. It covers what the tool does, what it returns, how to authenticate, and when to use an alternative. There is no output schema, but the description explains the return type (section headings and titles), which is sufficient for an agent to know what to expect. Nothing critical is missing for correct invocation.

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 schema description coverage is 100%, meaning both parameters ('query' and 'limit') are described in the schema. The schema already explains that 'query' is the subject matter and 'limit' is the maximum results. The description reinforces this by giving examples in the schema, but it doesn't add new semantic detail beyond what the schema provides. The description does not elaborate on parameter format or edge cases, but since the schema is sufficient, 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 begins with a clear verb-resource pair ('Search the United States Code by subject') and specifies what it returns ('matching section headings and their titles'). It also explicitly distinguishes itself from usc_section, which is a sibling tool, by stating that usc_section is for fetching the full text of a known citation. This clearly differentiates the two tools and leaves no ambiguity about what this tool does.

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 usage guidance: it tells the agent to use this tool when searching by subject and to use usc_section when a citation is already available. It also mentions the key requirement (data.gov API key) and that usc_section is keyless, which helps the agent choose the more efficient path. This is explicit when-to-use and when-not-to-use guidance, naming the alternative directly.

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