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

Annotations already cover safety (readOnly/true, idempotent, non-destructive, open-world), and the description layers substantial extra behavior on top: every snippet carries citation, source URL, retrieval time, and a current-through or vintage label; stale:true marks hits whose source lags upstream; vintage text is a dated snapshot, not current law. It also discloses the meaning_only fallback and that unhosted requested ids surface in a response note.

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?

Purpose is front-loaded in the first two sentences, followed by scoping, then response semantics. It is dense and the parenthetical jurisdiction example and the stale/vintage sentences both carry weight, but the parenthetical '(e.g. us, us-tx; us-cfr scopes to the CFR alone...)' is partially duplicated by the jurisdictions and sources schema descriptions.

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?

With 8 parameters and no output schema, the description has to explain the return shape, and it does thoroughly: snippet fields, source URL, retrieval time, current-through vs vintage labels, stale flags, meaning_only semantics, and the note listing unhosted ids. Pagination behavior is only implied by limit/offset, which the schema covers, so an agent has what it needs to call and interpret this 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?

At 75% schema coverage the schema already documents most parameters, but the description adds real semantics the schema lacks: it explains the difference between us-cfr (CFR alone) and us (US Code plus CFR) for the jurisdiction/source ids, and clarifies that an address is resolved first and then scopes to its stack's hosted sources. Mode and limit/offset get no extra treatment, but they are documented in the schema.

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?

Opens with a specific verb+resource ('Search original law') and immediately adds the query surface (topic, question, or citation) plus the fact that exact citations resolve directly. It carves out territory against law_get_section by noting sections over 64KB require get, though law_get_section and law_for_location are never named directly.

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 says to pass address or jurisdictions, not both, and that sources should be used instead of jurisdictions/address. It also gives a clear escape hatch for oversized sections ('sections over 64KB require get'). What's missing is a direct statement of when to call law_for_location or law_coverage instead of using the address/id parameters here.

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