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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations by stating it 'returns ranked provisions with verbatim citations, headings, and snippets,' informing the agent about output shape and ranking behavior. It does not discuss pagination or rate limits, but for a search tool with an output schema this is sufficiently transparent.

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?

Every sentence earns its place: purpose, usage rationale, return format, workflow sequencing, and jurisdiction scoping are all packed into a compact description. The most important information is front-loaded, and the reference to sibling tools is woven in naturally. No filler or redundant repetition of the schema.

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 annotations, full schema coverage, and presence of an output schema, the description covers everything needed to select and invoke the tool correctly. It explains what the tool returns, how it relates to law.get_node, and how to scope with jurisdiction. There are no significant gaps that would leave an agent uncertain.

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 description coverage is 100%, so the baseline is 3 because the schema already documents all four parameters well. The description reinforces the jurisdiction parameter by pointing to law.list_coverage and mentioning sub-jurisdictions, which is already in the schema. It adds no fundamentally new parameter meaning beyond what the schema provides, so a 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 opens with a specific verb and resource: 'Search US federal, state, and municipal law by topic or keyword.' It clearly distinguishes itself from the sibling law.get_node by stating it discovers relevant law first, while law.get_node retrieves the full official text. An agent can immediately tell this is the search-and-discover tool among the siblings.

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?

Explicit guidance is provided: use it for any question about current law rather than relying on training data, and call it first before law.get_node. It also instructs the agent to pass jurisdiction and consult law.list_coverage for valid codes, naming the exact alternative for scoping. This leaves no ambiguity about when or how to invoke the tool.

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