patent_search

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses auth requirements (EPO_OPS_CONSUMER_KEY/SECRET, USPTO_API_KEY), backend reliability (google_patents 'often unavailable'), concurrency and failure behavior (auto mode queries worldwide + ppubs concurrently, falls back to uspto_odp once tagged with _note), and latency cost (~5-30s for seminal). It also reveals ranking defaults and that sort_by only affects ppubs. This is exactly the operational context an agent cannot infer from annotations alone.

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 densely informative with the core purpose front-loaded and zero filler sentences — every clause carries operational substance. However, the four backend profiles are crammed into a single pipe-separated run-on that is harder to scan than a structured list would be, and the auto-mode/fallback behavior is buried mid-paragraph rather than given its own sentence.

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 11 parameters, four backends, a fallback contract, and a co-citation feature, the description covers nearly every invocation-relevant behavior. The one gap is the shape of the returned result entries, which matters more because no output schema exists; mentioning seminal_prior_art and the _note tag partially compensates by naming the non-obvious return fields. Overall this is complete enough for an agent to call and interpret the tool 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: what each source enum value actually does (coverage scope, credential needs, availability), why quoting matters for the query param, and how the seminal flag produces seminal_prior_art via co-citation mining. It correctly notes that sort_by affects only the ppubs backend, reinforcing the schema. It doesn't walk all 11 params, but with full schema coverage it doesn't need to.

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 opening sentence states a specific verb and resource with explicit scope: 'Search patents worldwide (US, EP, WO, JP, and 100+ authorities).' The detailed backend breakdown (ppubs, ops, uspto_odp, google_patents) reinforces that this is a broad multi-source search facility, clearly distinct from patent_get and the other domain-specific search siblings. Nothing about the tool's purpose is left vague or implied.

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 gives explicit conditions for backend selection: ppubs is keyless and the default US backend, ops requires EPO_OPS credentials, uspto_odp requires USPTO_API_KEY, and google_patents is 'often unavailable' — plus the auto-mode fallback rule. It also prescribes how to form queries ('Quote exact multi-word concepts... to avoid off-topic matches'). However, it never explicitly routes to sibling tools such as patent_get for ID-based retrieval, so exclusions are inferable rather than stated.

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