uspto_ptab_decisions

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat safety. It adds the search scope (institution decisions, final written decisions, other rulings) which is useful but not behavioral beyond that. No mention of pagination, result limits, or response format, though the schema covers limit/offset. The description adds some value but does not significantly expand behavioral context beyond annotations.

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 two sentences with no filler. The core action is front-loaded ('Search PTAB trial decisions'), followed by specific types of rulings and search dimensions. Every word earns its place; it is concise and well-structured.

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 tool has 7 parameters, no output schema, and read-only annotations, the description covers the primary purpose and search dimensions. It does not explain query syntax (e.g., field names like 'trialMetaData.trialTypeCode'), but the schema provides examples. It also omits pagination behavior, but that is in the schema. Overall, the description is sufficient for an agent to understand what the tool does and roughly how to use it, with gaps that are minor given the schema's completeness.

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 all parameters are already described. The description lists high-level search dimensions (trial type, outcome, patent owner, grant date range) that map to fields used in queries, but does not add syntax or format details beyond the schema. Since the schema already documents each parameter, the description adds marginal semantic value, consistent with a baseline of 3.

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 clearly states the tool's purpose: 'Search PTAB trial decisions.' It specifies the resource (PTAB decisions) and the action (search), and distinguishes it from sibling tools like uspto_ptab_proceedings (which handles proceedings) and uspto_petition_decisions (petition decisions). It also lists search dimensions (trial type, outcome, patent owner, grant date range), making the scope explicit.

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 implies when to use this tool (for PTAB decisions) but does not explicitly contrast it with alternatives like uspto_ptab_proceedings or uspto_petition_decisions. It lacks guidance on when NOT to use it or how to choose between similar tools. Since the purpose is clear, an agent could infer usage, but explicit exclusions are missing.

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