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

With no annotations, the description carries the behavioral burden and does well: it discloses the return shape (matching sections with headings and excerpts), the resolved:true flag semantics, and the important caveat that only loaded states resolve to text while others return the citation as written. It omits operational details like pagination or auth, but the substantive behavioral traits are covered.

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?

Front-loaded with the verb+resource and endpoint, then layered with use cases, return shape, and the coverage caveat. Four dense sentences, all earning their place, though it packs multiple ideas closely together.

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?

No output schema and no annotations, so the description must explain returns and caveats, which it does (headings, excerpts, resolved flag, coverage limitation). An agent has enough to call it correctly; only minor gaps like default limit behavior remain, and those are handled by the schema.

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 75%, so the schema documents q, state, and code itself. The description implies the state-scoping constraint ('only states whose code is loaded') but adds no new syntax or semantics for q, code, or limit beyond what the schema already states, so it sits at the baseline.

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?

States a specific verb (full-text search) and resource (a state's codified law), and even gives the endpoint GET /v1/statutes/search. It distinguishes itself from siblings by naming get_statute for full section retrieval and list_statute_coverage for coverage, so an agent can route without opening any schema.

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?

Explicitly names when to use it ('what does the law say about X', finding the section a bill or ballot measure changes) and points to the alternative (get_statute) for fetching whole sections. The coverage caveat plus pointer to list_statute_coverage preempts a common misuse.

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