legal_research

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

Annotations already declare readOnly, idempotent, and openWorld hints. The description adds valuable behavioral context: it is a multi-step chain, combines multiple source types, and reports every step's outcome even when nothing is found. This goes beyond the structured annotations and helps the agent set expectations.

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?

Two sentences, front-loaded with the main behavior and key differentiation. Every clause earns its place: 'multi-step', 'combines sources', 'reports every step's outcome', and the task example. No waste.

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 complex 8-parameter tool with no output schema, the description gives the essential behavior ('multi-step chain', 'reports every step's outcome') and directs the user to the task parameter. But it doesn't mention authentication parameters or what the returned research report contains beyond step outcomes. Still, given the schema's rich task descriptions, it's reasonably complete.

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 63% and each parameter has a detailed description, especially 'task' with a full enum explanation. The description highlights 'task' as the primary control but doesn't add meaning for undocumented parameters like the API keys. It provides some orientation but largely relies on 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?

The description states a specific verb ('Run a multi-step legal research chain') and resource ('statute, regulation and case-law lookups'), clearly distinguishing it from single-lookup siblings like search_law or get_law_text. It also explains the unique value of combining sources and reporting all outcomes.

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?

It gives clear guidance on using the 'task' parameter to select research shape, with an explicit example for document_review. It implies this tool is for multi-step research but doesn't explicitly state when to prefer it over simpler alternatives, so it loses a point.

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