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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context by enumerating what comes back: configuration status (API keys, credentials), connection availability, and rate-limit information where available.

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?

Front-loaded one-line purpose, then a labeled trigger block, then a scannable bullet list of return contents. Every sentence carries information and nothing is redundant padding.

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 no output schema, the description must carry the return-value burden, and it does so by listing the three categories of status reported. Combined with the annotations covering the safety profile, an agent has everything needed to invoke and interpret this no-arg diagnostic tool.

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?

The tool takes zero parameters, which sets the baseline at 4. The description correctly does not invent parameter semantics, and the empty schema confirms there is nothing further to document.

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 names a specific verb and resource ('Check status and availability of all patent and trademark data sources') and clearly occupies a diagnostic niche distinct from every sibling, which all retrieve substantive patent/trademark data. An agent can tell instantly that this is a health-check tool, not a data-fetch tool.

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 an explicit trigger via 'USE THIS TOOL WHEN: You encounter errors or want to verify which APIs are available ... before starting research', covering both reactive and preflight contexts. It stops short of stating when not to use it or naming a fallback sibling, so it is clear context rather than full when/when-not/alternatives guidance.

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

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

Goes well beyond the readOnly/idempotent/openWorld annotations by disclosing the data provenance split (bundled table for sections/classes vs. USPTO scheme page for subclasses/groups), the fetch cost ('one fetch per subclass per day, no key'), and the degradation path ('scheme_error' fallback to static titles). That is exactly the operational context an agent cannot infer from 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?

Front-loads the one-line purpose, then organizes the rest into labeled WHEN and Args/Returns blocks so an agent can skim. Length is justified by the accepted-input variety and the branchy return shape; no sentence is filler.

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 no output schema, the description supplies the return contract at every depth (section title/description/classes; class titles; subclass/group title, level, hierarchy, direct children, source page) plus the partial-failure case. For a 1-parameter tool this leaves nothing an agent needs missing.

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 0% — the single parameter has no description — so the description carries the full burden and does so thoroughly, enumerating accepted forms: compact ('G06N3/08'), spaced ('G06N 3/08'), PPUBS-style with date ('H04B7/0417 20130101'), and bare hierarchy prefixes ('G06N', 'G06', 'G'). This is meaning the schema does not supply.

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?

States a specific verb (look up) and resource (a CPC symbol) with the exact depths supported (section, class, subclass, main group, subgroup) and explicitly what it returns at each depth. No sibling tool covers CPC classification, so the agent can rule out the rest of the list immediately.

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 'USE THIS TOOL WHEN' block gives concrete triggering contexts — reading CPC codes off a patent or selecting codes for a `.cpc.` search — which is clear positive guidance. It stops short of naming an alternative or stating when not to use it, but that is largely because no sibling does CPC lookup.

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

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

Annotations only cover the read-only/idempotent/open-world profile, so the description adds real operational context: data starts around 2012, rows lag mailing by about a week, and rows contain no mail date, plus the workaround of using the rejection dataset to pin down the day. Missing rate limits and nothing on behavior when no filter is supplied, which keeps it out of the top score.

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?

Front-loads the one-line purpose, then routes with when-to-use and cheaper alternatives, then coverage caveats, then args, then returns. Because the schema itself has zero field descriptions, the per-argument block is not redundant and every sentence earns its place.

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?

The returns fields are enumerated in prose (necessary since there is no output schema), coverage limits are disclosed, and all filters are explained. The one unaddressed case is that zero parameters are required, yet nothing says whether an unfiltered call is valid or would sweep the whole corpus; a note on that (and on offset/limit paging behavior) would make it fully 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 description coverage is 0%, so the description carries the full burden and does: it documents all 12 parameters with formats ('18402543' without slashes, YYYY-MM-DD), inter-parameter dependencies (mail_date needs application_number or patent_number), accepted input variants for cited_reference, the meaning of legal_section values, and the 200-row cap on limit.

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?

States a specific verb+resource (retrieve prior-art references examiners cited in office actions) and explicitly separates itself from the nearest siblings get_office_action_rejections, ppubs_get_citing_patents and ppubs_get_patent_by_number. The reverse-lookup mode (which applications cited a given reference) is called out, so an agent can identify the tool without reading the schema.

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?

A dedicated 'USE THIS TOOL WHEN' block gives both forward and reverse lookup conditions, and names cheaper alternatives with the exact condition that selects them (front-page citations -> ppubs_get_patent_by_number(sections=["biblio"])). Nothing about when-to-use or when-to-use-something-else is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds substantive behavior beyond them: coverage window (2012 on, 93M rows, ~1 week lag), a machine-extraction caveat ('treat them as a guide and read the action'), and the critical pagination quirk that offsets count rows not actions so an action can straddle pages.

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?

Front-loaded with purpose and usage, then cleanly sectioned into Args and Returns. It is long, but with 13 undocumented params the length is largely earned; a few arg descriptions (e.g., statute/case_law examples) are slightly redundant with the Returns list.

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 13-param, zero-schema-description tool with no output schema, the description supplies the return shape (document_id, app_num, document_code, mail_date, art_unit, statutes, case_law, claims, claim_groups), total row counting, and metadata.next_offset continuation. Nothing an agent needs to call it correctly is missing.

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 0% across 13 params, so the description carries the full burden and does so: it documents each arg with format and semantics (application_number without slashes, comma-separated statutes that must ALL apply, comma-separated cases that must ALL be cited, query as an AND-ed Solr clause, offset default 0, limit default 50/max 200). This adds meaning the bare schema lacks.

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?

States a specific verb+resource ('Get claim-level rejection data from office actions') and immediately distinguishes itself from siblings by naming odp_search_office_actions (for text) and odp_download_document (to read it). An agent can tell exactly what this returns versus adjacent tools.

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 'USE THIS TOOL WHEN' block gives concrete triggering conditions (which claims an examiner rejected/objected/allowed and under which statute, plus claim-level 101 analytics like case_law="alice", art_unit="3689"). It also routes the agent to alternatives for the action's text, covering both when-to-use and when-to-use-something-else.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the return shape (description plus examination stage), which is valuable since there is no output schema. It does not say how it behaves for an invalid code, a minor gap.

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?

Front-loaded one-line purpose followed by tightly scoped USE WHEN, Args, and Returns sections. Every sentence earns its place; the structured formatting is slightly heavier than needed for a single-parameter lookup.

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 trivial one-parameter lookup with no output schema, the description covers purpose, trigger, parameter semantics, and return values. Only the behavior on an unrecognized code is left unspecified.

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 0%, so the description must carry the parameter burden, and it does: it names the parameter, explains it is a status code number, and gives a concrete example ('30' for 'Docketed New Case'). It does not cover edge cases like unknown codes, keeping it short of a 5.

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 and resource: 'Look up USPTO application status code meaning.' The word 'application' distinguishes it from the sibling get_trademark_status_code, so an agent can route correctly, though no sibling is named explicitly.

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?

A distinct 'USE THIS TOOL WHEN' block gives an explicit triggering condition (encountering a status code in application data). It lacks a when-not clause or named alternative, but the trigger is unambiguous.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description usefully adds what the tool returns (class title, type, description), but says nothing about error behavior for out-of-range values or rate limits.

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?

Front-loaded one-line summary followed by clearly labeled USE/RETURNS/Args sections; every sentence contributes. The Args and Returns blocks are slightly verbose for a single-parameter lookup but remain scannable.

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 no output schema, the description correctly compensates by naming the returned fields, and the range/goods-services framing gives the agent what it needs to call the tool. Missing only edge-case behavior (invalid class numbers) and any format details for the returned description text.

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 0%, so the description carries the full burden, and it does: it defines the parameter as an international class number constrained to 1-45, and gives concrete examples ('9' for computer software, '25' for clothing, '42' for software services). It could mention the string-vs-integer expectation, but the examples imply string usage.

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?

States a specific verb and resource ('Look up a Nice/international trademark class (1-45)') and scopes it with the goods/services split. This is clearly distinguishable from siblings like tsdr_get_trademark_status or get_cpc_info, so an agent can select it without opening the schema.

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 explicit 'USE THIS TOOL WHEN' block gives concrete triggers: needing to know what a class covers, or picking classes for a clearance search. It gives no explicit alternatives or when-not-to-use cases, but the triggers are unambiguous.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world, so the safety profile is covered. The description adds useful behavioral context by stating what is returned ('Status code description and prosecution stage'), which the annotations do not provide.

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, followed by a clear usage trigger and Args/Returns blocks. Efficient and scannable; the Args section lightly restates the schema but the structure is sound.

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 simple, read-only, single-parameter lookup with no output schema, the description covers what the tool does, when to reach for it, and what it returns. Nothing essential an agent needs to invoke it correctly is missing.

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 0%, so the schema's bare 'Code' string gives little, but the description compensates by naming the parameter as a 'Trademark status code' and supplying concrete value examples with meanings. This adds real semantic value beyond the schema for the single required parameter.

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?

States a specific verb (look up) and resource (USPTO trademark status code meaning), with the domain qualifier 'USPTO trademark' disambiguating it from the generic sibling get_status_code. However, it does not explicitly contrast itself with that sibling or with tsdr_get_trademark_status.

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 'USE THIS TOOL WHEN' line gives a concrete triggering condition ('Trademark data contains a numeric status code you need to interpret') and reinforces it with real examples (700=Registered, 686=Published for opposition). No when-not or explicit alternative routing is offered, so it stops short of 5.

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

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

Annotations already cover the read-only/idempotent/open-world profile, but the description adds substantial extra behavior: NO_TEXT_AVAILABLE for non-XML documents, OCR error risk on applicant papers, 24k-character paging with next_offset, a 4 MB refusal (RESPONSE_TOO_LARGE), and the USPTO_API_KEY requirement. Claim-markup conventions (~~deletions~~, ++insertions++) are also disclosed.

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?

Clear front-loaded purpose followed by WHEN / Args / Returns sections, and virtually every sentence carries operational information. It runs long and the Args block partly restates parameter names already visible in the schema, so it is dense rather than tight.

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 no output schema and no annotation-level detail, the description must supply everything an agent needs: both return shapes, the pagination contract, the failure modes (NO_TEXT_AVAILABLE, RESPONSE_TOO_LARGE), and the auth prerequisite. Nothing essential to a correct call is missing.

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 0%, so the description carries the full burden and does: app_num format without slashes, document_id provenance and an example, format's two legal values and the pdf default, and text_offset's exact meaning tied to the previous response's next_offset. No parameter is left ambiguous.

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?

States a specific verb and resource ('Read one file-wrapper document') plus the two output modes, which cleanly separates it from the sibling lookup tools that only return identifiers. An agent can tell this is the retrieval/read step of the odp document workflow without opening the schema.

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 'USE THIS TOOL WHEN:' block names the two feeding siblings (odp_get_documents, odp_search_office_actions) and the precondition (you have a document identifier). It also gives a positive preference ('Prefer format="text"') and states when the alternative (format="pdf") is needed.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, covering the safety profile. The description adds useful context on what PTA represents and why it's requested, but says nothing about rate limits, response contents, or data freshness. With annotations doing the heavy lifting, a 3 is appropriate.

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 purpose is front-loaded in one line, followed by a use-case trigger and parameter note. The 'Args:' block is slightly boilerplate for a single parameter but overall it is tight and earns its place.

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 single-parameter read-only lookup with no output schema, the description covers purpose, when to use it, and parameter format. It omits any hint of what the returned PTA data looks like, which is a minor gap given no output schema exists.

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 0%, so the description must compensate, and it does: it specifies the format ('without slashes') and gives a concrete example ('14412875') that the schema's bare 'App Num' string type does not convey. This is meaningful syntax guidance for the single parameter.

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 and resource: retrieving patent term adjustment (PTA) data. This is distinct from siblings like odp_get_application or odp_get_continuity, though it does not explicitly name or contrast those alternatives. An agent can identify the resource clearly.

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 explicit 'USE THIS TOOL WHEN' clause gives a concrete condition: calculating a patent's actual expiration date accounting for USPTO delays. It lacks any when-not guidance or named alternatives, but the positive trigger is clear and actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety and repeatability profile is fully covered. The description adds useful context about what is returned (filing date, status, basic info), but says nothing about rate limits, auth requirements, or error behavior for an invalid application number. Adequate given the annotation coverage, but not rich.

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?

Front-loaded purpose sentence, a scannable USE THIS TOOL WHEN clause, and a compact args/returns block. Every line earns its place and nothing is padded.

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 single-parameter, read-only lookup with full annotation coverage and no output schema, the definition tells the agent what it gets and how to format the input. The one real gap is sibling disambiguation against odp_get_application_metadata and odp_get_documents, which the description never addresses.

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 0%, so the description must carry the parameter burden – and it does: it specifies the format ('without slashes or commas') and gives a concrete example ('14412875'). That is genuinely beyond what the bare string schema provides, though it doesn't state whether leading zeros or check-digit variants are accepted.

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?

States a specific verb+resource ('Get patent application data') plus the data source (USPTO Open Data Portal), so the agent knows what it retrieves. However, it does not distinguish itself from the closely-named sibling odp_get_application_metadata, whose scope ('basic metadata') appears to overlap with this tool's stated 'basic info', leaving an ambiguity an agent must resolve by guessing.

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?

An explicit 'USE THIS TOOL WHEN' clause gives a clear triggering condition: needing prosecution/file wrapper data (status, dates, metadata). It stops short of naming when NOT to use it or pointing at alternatives, and gives no guidance for cases that fit both this tool and odp_get_application_metadata or the odp_search_* family.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered structurally. The description adds only that the payload includes examiner/art-unit/status content; it says nothing about auth requirements, rate limits, or error behavior on invalid application numbers.

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?

Short and front-loaded: the purpose sentence comes first, followed by the usage condition and parameter note. The 'Args:' boilerplate is slightly redundant but the example earns its place.

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?

There is no output schema, and the description partially fills that gap by naming the returned fields (examiner info, art unit, status). For a single-parameter read tool this is largely sufficient, with the main omission being how it differs from odp_get_application.

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 0% – the schema only declares a string with no description. The description compensates by specifying the format constraint ('without slashes') and a concrete example ('14412875'), which is exactly the detail an agent needs to form a valid call.

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?

States a specific verb and resource: 'Get detailed metadata for a patent application'. The 'detailed' qualifier hints at depth, but the description never distinguishes this from the sibling odp_get_application, so an agent must guess which metadata tool to pick.

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 'USE THIS TOOL WHEN' block gives a clear triggering condition and enumerates what the response covers (examiner info, art unit, detailed status). It stops short of naming an alternative or stating when not to use it, which matters given the near-identical sibling odp_get_application.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered structurally. The description adds one useful behavioral fact — that results include historical as well as current owners — but says nothing about permissions, rate limits, or result size.

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?

Three short blocks — purpose, when-to-use, args — with the resource and trigger front-loaded and the parameter format detail last. No sentence is redundant and nothing important is buried.

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 single-parameter read tool with no output schema, the description covers purpose, trigger, and parameter format, and clarifies that the target may be a patent or an application. It stops short of describing the returned record's shape or whether results can span multiple assignments.

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 0% and the single parameter has no title-level documentation, so the description must compensate — and it does, specifying 'Application number without slashes' plus a concrete example ('14412875'). That format constraint is exactly the kind of detail an agent would otherwise get wrong.

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?

States a specific verb and resource ('Get patent assignment/ownership records') and the parenthetical scope 'current and historical owners' clarifies what kind of record. The 'patent' qualifier implicitly separates it from the trademark-side sibling tm_search_assignments, but no sibling is named explicitly, so it falls just short of 5.

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 explicit 'USE THIS TOOL WHEN: You need to know current and historical owners of a patent or application' gives a clear triggering condition. It offers no when-not guidance and names no alternative (e.g., tm_search_assignments for trademarks, or odp_get_application for general bibliographic data), so it stops at 4.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds nothing behavioral beyond the purpose statement (no data source, no handling of missing attorneys, no freshness/return-shape context). With annotations carrying the burden, the description's contribution here is minimal.

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 lines and front-loads the purpose before the argument detail. The 'Args:' block is docstring boilerplate but its content (format + example) earns its place; nothing else is wasted.

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 single-parameter read-only lookup with annotations covering safety and no output schema, the description supplies the essential purpose and the non-obvious input format. Remaining gaps (behavior when no attorney of record exists, data source) are minor for a tool this simple.

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 0% and the schema only exposes 'app_num' with no description, so the description must compensate. It does so with a concrete format rule ('without slashes') and an example value ('14412875'), which is exactly the kind of input-format detail an agent needs to construct a valid call.

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 and resource: get the attorney/agent of record for an application. This is clearly distinguishable from siblings like odp_get_application or odp_get_assignment, though it never explicitly contrasts itself with them. Purpose is unambiguous.

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?

There is no guidance on when to use this tool versus related ODP getters, no prerequisites, and no mention of what to do when no attorney is on record. The description only states what the tool does, not when to reach for it.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds only a brief statement of what the return contains (parent/child relationships, priority claims); it says nothing about auth, rate limits, or empty-result behavior.

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?

Front-loaded one-line purpose followed by terse labeled sections (WHEN/Args/Returns). No filler, though the template headers add slight verbosity relative to the tiny payload.

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 single-parameter read tool with no output schema, the description covers purpose, trigger, argument format, and return content. It is adequately complete; only edge-case behavior (no family found, invalid app number) is unaddressed.

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?

With one parameter and 0% schema description coverage, the description carries the burden and does compensate: it specifies the format ('without slashes') and gives a concrete example ('14412875'), which an agent needs to form a valid call. It doesn't note validation or error behavior.

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 first line states a specific verb and resource ('Get patent family/continuity data') and clarifies the scope with 'parent and child applications'. It is distinguishable from siblings like odp_get_foreign_priority, though it never names an alternative to sharpen the boundary.

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 'USE THIS TOOL WHEN' block gives clear context (understanding the family tree – parents, continuations, divisionals, CIPs), which is genuinely helpful selection guidance. It stops short of exclusions or naming a sibling tool to use instead.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds only the 'bulk dataset product' framing and nothing about return shape, rate limits, or auth, so with the lowered bar it is adequate but thin.

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?

Extremely short and front-loaded, with the core action stated first. The Args block is boilerplate but harmless given a single parameter.

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 simple get-by-id tool with full annotation coverage and no output schema, the description is minimally sufficient. It omits where product_id comes from and gives no sense of what 'details' are returned, which an agent would want for a bulk dataset lookup.

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 0%, so the description must carry the burden. It labels product_id as a 'Dataset product identifier,' which adds minimal semantic value beyond the parameter name, but at least confirms it is an identifier rather than free text.

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?

States a specific verb and resource: 'Get details of a specific bulk dataset product.' An agent can distinguish it from the sibling odp_search_datasets by the 'specific' qualifier, though the contrast is implicit rather than stated.

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?

No when-to-use guidance, no prerequisites, and no mention of odp_search_datasets as the way to discover the product_id this tool requires. The only hint of context is 'specific,' which leaves the agent to infer that an identifier must already be known.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive behavior. The description goes further by describing sort order (newest first), returned fields (documentIdentifier, documentCode, dates, page count, formats), pagination via offset/limit, direction categories, and metadata.code_counts, adding substantial context beyond the 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?

Front-loads purpose, then usage, args, and returns, with clear headings. The document-code examples are lengthy but directly useful for an undocumented parameter; no sentence is redundant.

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?

No output schema exists, but the description describes the return shape and key fields. For a 5-param listing tool with rich annotations and complex filtering, the description supplies enough context about arguments, behavior, and return format to call it 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 description coverage is 0% and the schema provides no descriptions or enums, so the description carries the full burden. It defines app_num format, explains document_code syntax and lists common codes, specifies direction values, and gives defaults for offset and limit—compensating completely.

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?

States a specific verb ('List') and resource ('documents in an application's file wrapper'), and disambiguates from the download tool by naming odp_download_document as the read step. An agent can identify this as the prosecution-history listing tool without opening the schema.

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?

Provides an explicit 'USE THIS TOOL WHEN' section enumerating document types and names the follow-up tool for reading a single document. It does not say when to prefer this over sibling search tools like odp_search_office_actions, nor does it state when not to use it, so it falls short of full when/when-not/alternatives coverage.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and openWorld, covering the safety profile. The description adds semantic value by explaining the claims may affect the effective filing date, but says nothing about return format or result shape. Given annotation coverage, a 3 is appropriate.

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?

Front-loaded purpose sentence followed by a usage cue and the arg format; nothing is redundant. The "USE THIS TOOL WHEN" header and Args section add slight boilerplate but remain efficient.

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 simple single-param read-only tool, the description covers purpose, when to use it, and the parameter's required format. No output schema exists, but the description needn't explain return values; only a brief hint on returned claim contents would push this higher.

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 0%, so the description carries the parameter burden. It documents the single param's format ("Application number without slashes") and gives a concrete example ("14412875"), which is exactly the missing detail the schema omits.

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?

States a specific verb (Get) and resource (foreign priority claims for an application), which is concrete and unambiguous. It does not name a sibling or explicitly distinguish itself from related tools like odp_get_continuity or odp_get_application, so it stops short of a 5.

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?

"USE THIS TOOL WHEN: You need to find priority claims to foreign applications that may affect the effective filing date" gives a clear triggering condition. It lacks explicit exclusions or named alternatives, so it is clear context rather than full routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety and repeatability profile is covered. The description adds useful content scope (what event types are included) but says nothing about pagination, result volume, or whether the full history is always returned — modest added value over the 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?

Two short blocks with zero filler: the purpose sentence first, then the selection trigger, then the argument format. Every line earns its place and the reader gets the essential facts immediately.

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 single-parameter read tool with no output schema, the description covers purpose, selection trigger, and argument format adequately, and its enumeration of event types substitutes partially for a missing return schema. The remaining gap — result size/pagination behavior — is minor given the annotations and tool simplicity.

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 0%, so the description must carry the parameter burden, and it does: it specifies the format ('without slashes') and gives a concrete example ('14412875'), which is exactly the kind of detail the bare schema lacks. It does not add anything further, but for a single required string parameter this is sufficient.

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?

States a specific verb and resource: 'Get prosecution transaction history for an application.' The parenthetical content (office actions, responses, fee payments) clarifies the resource scope, distinguishing it reasonably from sibling tools like odp_get_documents or odp_search_office_actions, though it never names those siblings explicitly.

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 'USE THIS TOOL WHEN' block gives a clear selection condition — needing the complete prosecution timeline rather than a subset of events. It provides positive guidance but no when-not condition and does not point to alternatives such as odp_get_documents for actual document retrieval.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral detail beyond that: typed filters are AND-ed, OR requires a Lucene string in `query`, and defaults are stated for offset/limit. It stops short of describing result normalization details or rate limits.

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?

Front-loaded with purpose, then a clearly delimited usage block, then Args, then Returns. Given 0% schema coverage the parameter list is necessary rather than padding, and no sentence is redundant.

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?

No output schema exists, and the description gives only a thin return statement ('Normalized response with matching applications'). For a 9-parameter search tool it is otherwise complete: all filters, formats, and the AND/OR semantics are covered, but pagination behavior (whether offset+limit is the only paging mechanism, total counts) is left implicit.

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 0%, so the description carries the full burden, and it does: every one of the 9 parameters is documented with meaning and format ('filing_date_from: Filing date range start (YYYY-MM-DD)', 'inventor_name: matches first inventor'). The Lucene example clarifies the otherwise opaque `query` field.

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?

States a specific verb and resource ('Search patent applications in USPTO Open Data Portal') and immediately differentiates itself from the PPUBS sibling by scoping to filtering not available there. An agent can distinguish it from ppubs_search_applications and the many odp_get_* tools without opening any schema.

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 'USE THIS TOOL WHEN' block gives an explicit triggering condition ('filtering by applicant metadata, dates, or other criteria not available in PPUBS'), which is concrete usage guidance. It references PPUBS as the alternative but not by exact tool name, and offers no when-not guidance, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, covering the safety profile. The description adds no behavioral context of its own — no pagination semantics, no result shape, no rate limits — so it does little beyond the structured data.

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, the trigger sentence follows, and the args list is compact. Nothing is padded, though the Args block largely restates schema defaults rather than adding new information.

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 annotations present and only three optional parameters, the description plus schema is nearly sufficient for correct invocation. The main residual gap is that no output schema exists and the description doesn't hint at what a result record contains.

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 0%, so the description must carry the parameter burden, and it does: query, offset (starting position, default 0) and limit (max results, default 25) are all explained. It compensates for the empty schema, though the semantics remain minimal.

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?

Names a specific verb+resource: 'Search USPTO bulk data products/datasets', which is distinguishable from the sibling odp_get_dataset by the search verb. It stops short of an explicit sibling comparison, so it lands at a clear-but-undifferentiated 4.

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 'USE THIS TOOL WHEN' block gives a concrete trigger — finding bulk download datasets for large-scale analysis — which is more than implied usage. It omits the natural exclusion (once you have a dataset ID, use odp_get_dataset), so no alternative is named.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, yet the description adds substantial non-obvious behavior: text_preview is capped at 500 characters while the API still searches full text, coverage starts mid-2007 with 19.9M records, typed filters are AND-ed versus Lucene OR, and metadata.facets enables counting with limit=1. It even routes the agent to odp_download_document(format="text") to read a hit.

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 long but front-loaded and sectioned (purpose, USE THIS TOOL WHEN, IMPORTANT caveat, Coverage, Args, Returns). Every sentence is load-bearing given 0% schema coverage and no output schema; nothing is repeated from structured fields.

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 no output schema, the Returns block enumerates the returned fields and metadata.facets; with 12 undocumented params, the Args block documents each. Caveats, coverage window, alternative tools, and result-reading workflow are all present, so an agent has everything needed to call it 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 description coverage is 0%, so the description carries the full burden and does so for all 12 parameters: format examples for app_num, the patent-to-application resolution, the enumerated document_code values (CTNF/CTFR/NOA/CTRS/CTAV/APEA/PETDEC), the rejection_type list, date format, sort values, and limit/offset defaults with the 100 cap. This adds meaning far beyond the bare 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 first line states a specific verb+resource+scope: search office actions across all applications by examiner text. It explicitly differentiates from the sibling odp_get_documents ("For one application's history, odp_get_documents is cheaper"), so an agent can route between them without opening either schema.

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 "USE THIS TOOL WHEN" block enumerates concrete triggering conditions (free text, statute, art unit, date, counting) and names the cheaper alternative with the condition that selects it. It also explains the AND/OR filter semantics, which directly affects whether an agent uses this tool or builds a Lucene query.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), but the description layers on substantial non-obvious behavior: 1.1M records from 1991, OCR noise with a concrete degraded example ('EENITED STATES') and a proximity-search workaround, facet-based grant-rate aggregation in one call, the exact meaning of final_only (currently the DENIED set), and the ~1.5-3k character cost per record for include_full_text.

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?

Well front-loaded and organized under Purpose / When / Coverage / Args / Returns headings, with no filler sentences. It is long, but nearly all of that length is load-bearing documentation for 15 undescribed parameters, so the size is defensible rather than padded.

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?

Despite no output schema, the 'Returns' section describes the returned fields (record_id, dates, petition type, outcome, deciding office, final_decision, marked-up text excerpt) and includes the hand-off to odp_download_document using documentIdentifier plus app_num for the full decision letter. Nothing needed to call or chain this tool is missing.

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 0% across 15 parameters, so the description carries the full burden and does so: every parameter is documented with format, examples, and semantics (app_num without slashes, petition_type as numeric code or description words, outcome enumerations, date format YYYY-MM-DD, record_id provenance, sort/offset/limit defaults and the 100 cap).

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?

States a specific verb and resource ('Search USPTO decisions on patent petitions') and immediately scopes it to the Office of Petitions domain, which cleanly separates it from siblings like ptab_search_decisions, ptab_search_appeals, and odp_search_office_actions. An agent can identify the correct tool without opening the schema.

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?

An explicit 'USE THIS TOOL WHEN' block enumerates the concrete petition scenarios (revival of abandoned applications, reinstatement after missed maintenance fee, delayed priority claims, petitions to make special, supervisory review). It further tells the agent when to use `query` (searching argument text) and when typed filters suffice, plus the OR vs AND semantics that decide between the two paths.

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

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

Annotations already declare read-only, idempotent and non-destructive behavior, so the bar is lower; the description still adds real context by disclosing the base64 payload format and warning that Claude Desktop may not fully support PDF display. It omits anything about size limits or failure modes for invalid patent numbers.

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?

Front-loaded with the core action, then a short usage line, args, and return shape; every section earns its place. The "Args:"/"Returns:" scaffolding is slightly boilerplate-heavy for one parameter but not wasteful.

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 no output schema, the description correctly describes the return value (dictionary with base64 PDF data) and flags the client-side display caveat that an agent would otherwise discover only by failing. Failure behavior for an unresolvable patent number is the remaining gap.

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 0% for the single parameter, so the description carries the burden, and it does so with concrete accepted formats ("7123456", "US 10,000,000 B2", "D845123", "RE49123"). That materially reduces trial-and-error, though it doesn't state whether non-US or application numbers are accepted.

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?

States a specific verb (Download) plus resource (patent PDF) and the encoding (base64), which is enough for an agent to know exactly what it gets. It does not explicitly distinguish itself from near-siblings like ppubs_get_full_document or ppubs_get_patent_by_number, so it stops short of a 5.

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?

"USE THIS TOOL WHEN: You need the official PDF document of a patent" gives a clear triggering condition. There is no explicit when-not guidance or named alternative for agents that only need text/metadata rather than the PDF, which keeps it at 4.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantive context beyond them: the search targets the .urpn. references-cited field, pending applications are not indexed so unissued citing applications are excluded, and it notes a live verification date. That coverage limitation is exactly the kind of behavior an agent cannot infer from structured fields.

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?

Well front-loaded: purpose, when-to-use, mechanism/caveats, then Args and Returns sections. The 'working replacement for the decommissioned Enriched Citation API' line and the verification date are marginal but defensible context; otherwise every sentence earns its place.

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 no output schema, the description still documents return shape (normalized search response, `total` as forward-citation count, per-result GUID/title/dates/inventors/classification). Combined with full parameter coverage and the index caveat, nothing needed to call it correctly is missing.

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 0%, so the description carries the full burden and does: patent_number accepts multiple formats ("7123456", "US 10,000,000 B2", "D845123", "RE49123"), offset is for pagination, limit defaults to 20 with a max of 500, and sort defaults to "date_publ desc" meaning newest citing patent first.

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?

States a specific verb+resource with scope: 'Find later granted patents that cite a patent (forward citations).' It explicitly distinguishes the direction of citation from the sibling ppubs_get_patent_by_number, which returns backward citations, so an agent can route correctly without opening either schema.

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?

A dedicated 'USE THIS TOOL WHEN' block gives concrete intent triggers (who built on a patent, gauge influence, find later art) and names the alternative tool and its arguments for the opposite need (backward citations via ppubs_get_patent_by_number with sections=["biblio"]).

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

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

Annotations already cover read-only/idempotent/open-world, so the description correctly spends its budget on behavior they cannot express: typical document size (20-40k tokens, mostly description), the fact that omitting `sections` returns everything, per-section token economics, and that empty/highlight fields are dropped. This is materially useful operational context.

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?

Front-loaded purpose and usage guidance, with Args/Returns blocks that are easy to scan. The per-argument prose is slightly long for a three-parameter tool, but every sentence carries actionable content, so waste is minimal.

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 no output schema, the description still states the return shape ('document with the requested sections') and the field-dropping behavior, and it warns about token cost before the call. Nothing essential is missing for correct invocation.

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 0%, so the description must carry the load and it does: it gives a GUID example, enumerates source_type values ('USPAT', 'US-PGPUB'), and defines every section token ('biblio', 'abstract', 'claims', 'description') plus the default (omit = everything) and a recommended combination.

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?

States a specific verb and resource ('Get complete patent document by GUID from PPUBS') and clarifies the retrieval channel ('GUID from search results'), which separates it from siblings like ppubs_get_patent_by_number and ppubs_download_patent_pdf. An agent can identify the tool without opening the schema.

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 'USE THIS TOOL WHEN' block names the precondition (you already have a GUID from search results) and offers a scoped alternative (request `sections` when you need less). The routing condition is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive behavior, so the safety profile is covered. The description adds genuinely useful non-annotation context: a whole document is 20-40k tokens dominated by the description, and empty/highlight fields are dropped from the response. That token-budget guidance is exactly the kind of behavioral cost disclosure an agent needs to plan a call.

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?

Front-loaded with the one-line purpose, then clearly delimited USE THIS TOOL WHEN, Args and Returns blocks. No sentence is filler: the token-cost aside and the per-value section explanations all change how an agent would invoke the tool.

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 only two parameters, no output schema, and annotations covering safety, this description supplies everything needed to call correctly: the required identifier's accepted formats, the optional filter's vocabulary, expected document size, and what is trimmed from the result. Nothing material is missing.

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 0%, so the description must carry the full parameter burden, and it does. It spells out normalization rules for `patent_number` (separators, leading 'US' and kind codes ignored; design/reissue/plant prefixes kept) with four worked examples, and enumerates every legal value of `sections` with meaning and a concrete recommended combination.

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?

States a specific verb and resource: 'Get a granted patent's full text by patent number.' An agent immediately knows what it retrieves. It does not, however, distinguish itself from the sibling ppubs_get_full_document, which sounds like it may overlap, so it falls short of the sibling-differentiation bar for a 5.

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 'USE THIS TOOL WHEN: You know the patent number and need the patent text' block gives an explicit trigger condition, and the token note routes the agent toward the `sections` parameter for lighter calls. It never names an alternative sibling (e.g. ppubs_search_patents or ppubs_get_full_document) or states when NOT to use it, so it is clear context without exclusions.

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

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

Annotations already declare readOnly/idempotent/open-world/non-destructive, so the safety profile is covered. The description still adds real behavioral context: the 18-month publication timeline, the token-budget truncation to 20 results, and the deprecation of legacy TTL//IN/ qualifier syntax. It doesn't describe pagination edge behavior or error conditions.

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?

Front-loaded purpose sentence, then labeled WHEN/Args/Returns blocks. Every sentence carries load — the syntax warnings and token-budget caveat are the kind of detail an agent needs to invoke correctly, not padding.

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?

No output schema exists, and the description only says 'Normalized response with application results', which is thin on return shape. However, for a search tool with annotations covering safety and thorough arg documentation, everything needed to make a correct call is present.

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 0%, so the description carries the full burden and does so for all four params: BRS dotted field qualifiers with deprecated forms called out, AND-ed multi-word semantics with quoting guidance, offset's pagination role, limit's default/max plus the token-budget caveat, and the sort default. This is well beyond a baseline compensation.

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?

States a specific verb+resource (search published US patent applications) and immediately scopes it to pre-grant publications that appear 18 months after filing, before grant. This clearly distinguishes it from ppubs_search_patents and from the odp_search_applications family without needing the schema.

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?

A dedicated 'USE THIS TOOL WHEN' block gives an explicit triggering condition (need pre-grant published applications), and the args note points to ppubs_search_patents as the syntax-equivalent sibling. It stops short of an explicit negative rule (e.g. 'for granted patents use X instead'), so it doesn't reach a full 5.

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

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

Annotations already establish this as a safe, idempotent, read-only operation, yet the description adds real operational context the annotations cannot: legacy slash-prefix syntax silently returns 0 results and TTL/"phrase" triggers a server 500, and results exceeding the token budget are truncated to 20 regardless of the limit. These are exactly the failure modes an agent needs warned about.

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?

Well front-loaded with clear USE THIS TOOL WHEN / Args / Returns sections, and the syntax examples are genuinely load-bearing. Minor redundancy: the 'date_publ desc' default and its effect on broad queries are restated after already appearing in the sort arg line.

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 no output schema and no schema descriptions, the description compensates fully: query grammar, pagination strategy, result caps, sort semantics, and a short Returns summary of fields (GUID, title, abstract, dates, inventors, classifications). An agent has everything needed to call 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?

Schema coverage is 0%, so the description must carry all four parameters, and it does: query is documented with BRS field qualifiers (.ti., .ab., .in., .as., .cpc., .pn.) and worked examples, plus default AND behavior; offset, limit (default 20, max 500, with truncation caveat) and sort (default 'date_publ desc') are each explained. This is far beyond what the bare schema provides.

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?

States a specific verb and resource ('Search granted US patents in Patent Public Search'), with scope narrowed to granted patents and full-text coverage, which implicitly separates it from the applications sibling. It never names ppubs_search_applications or ppubs_get_patent_by_number explicitly, so differentiation still requires the agent to infer from 'granted' vs 'applications'.

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 'USE THIS TOOL WHEN' block gives clear triggering conditions: full-text US patent search with daily updates, or access to the most recent filings. However, it offers no when-not guidance and does not name alternatives (e.g., ppubs_get_patent_by_number for known-number lookups), leaving the agent to infer the boundary.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds only 'Live via USPTO ODP v3.0', which hints at a real-time upstream source but says nothing about auth requirements, rate limits, caching, or what the response contains.

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 core sentence is short and front-loaded, with no filler. The trailing 'Args:' block is redundant with the input schema and could be dropped, but the overall footprint is appropriately small.

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?

There is no output schema, so the description is responsible for conveying what 'details' means and what comes back; it does not. Combined with a 0%-documented single parameter, the definition is too thin for an agent to invoke confidently.

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 0%, so the description must carry the parameter burden, yet it merely restates the schema title ('appeal_number: Appeal number'). It gives no format or example (e.g., the expected appeal number pattern), which is the one thing an agent actually needs here.

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?

States a specific verb (Get) and resource (details of a specific ex parte appeal decision), which distinguishes it from search-oriented siblings like ptab_search_appeals and ptab_search_decisions. It does not, however, distinguish itself from the nearby ptab_get_decision or ptab_get_proceeding, so the boundary is only partly drawn.

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?

No when-to-use guidance, no prerequisites, and no named alternatives. The closest thing to context is the provenance note 'Live via USPTO ODP v3.0', which tells the agent nothing about when this tool is the right choice over ptab_get_decision or ptab_search_appeals.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered structurally. The description adds only a minor data-source note ('Live via USPTO ODP v3.0') and no rate limits, auth needs, or result characteristics; with annotations doing the heavy lifting, this is a modest addition.

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 purpose is front-loaded in one sentence, followed by a compact args block. The 'Args:' formatting is slightly boilerplate for a single parameter, but the format example earns its place.

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 one-parameter read tool with annotations covering safety, the description is nearly sufficient, but with no output schema it never defines what 'details' actually contains, leaving the agent unsure of the response shape.

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 0% (the property is just 'Decision Id'), so the description must compensate, and it does: it defines the parameter as a decision identifier and supplies a concrete format example ('trial number, e.g. IPR2022-00001'). That is materially more than the schema provides.

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?

States a specific verb and resource ('Get details of a specific PTAB decision'), which clearly separates it from the sibling search tools like ptab_search_decisions. It does not name any sibling explicitly, but the singular-resource lookup framing makes the boundary obvious.

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?

No when-to-use, when-not-to-use, or alternative guidance is given. The framing implies you already hold a decision identifier, but nothing says how to obtain one (e.g. via ptab_search_decisions) or when this is preferable to search.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the useful detail that results are fetched live from USPTO ODP v3.0 rather than cached, and exposes paging via offset/limit, but says nothing about rate limits, result ordering, or what a response contains.

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 one-line purpose and data-source note are front-loaded, followed by a compact Args block. No filler sentences, though the arg list partially duplicates defaults already present in 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?

With a single required parameter, rich annotations, and no output schema, the definition covers invocation adequately. It falls short on the return side: an agent is not told the shape of a document record, whether a total count is returned for paging, or how document_type values are constrained beyond 'etc.'.

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 0%, so the description must carry the load, and it documents all four parameters including a format example for proceeding_number and enumerated examples for document_type. Defaults are restated from the schema, which is modest redundancy but the added example and type hints are genuinely useful.

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?

Specific verb (get) plus resource (documents filed in a PTAB proceeding), which clearly separates it from proceeding-level siblings like ptab_get_proceeding and decision-level ones like ptab_get_decision. It does not, however, explicitly distinguish itself from the similarly named odp_get_documents for patent applications, leaving that inference to the 'PTAB' qualifier.

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 says what the tool returns but never states when to reach for it over ptab_search_decisions, ptab_get_decision, or odp_get_documents, nor does it note prerequisites such as a valid proceeding number being required. Usage is only implied by the tool name.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world behavior, so the safety profile is covered. The description adds that the data is live from USPTO ODP v3.0, indicating freshness rather than caching, but says nothing about auth, rate limits, or error behavior for an invalid proceeding number.

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?

Front-loaded one-line purpose followed by compact Args/Returns blocks with no filler. The Returns list is slightly generic but earns its place given there is no output 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?

For a one-parameter read tool with full annotation coverage, the description supplies purpose, parameter format, data source freshness, and a summary of returned fields. Little an agent needs to invoke it correctly is missing.

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 0%, so the description carries the burden, and it delivers a concrete format example ('IPR2023-00001') for the single required parameter. This is genuinely useful for formatting the proceeding number correctly, though it stops short of stating format rules or validation behavior.

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?

States a specific verb and resource ('Get details of a specific PTAB proceeding') and scopes it to a single proceeding, which distinguishes it from the search-oriented siblings like ptab_search_proceedings. It does not, however, explicitly name those siblings to route the agent.

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?

Usage is only implied: the required proceeding_number argument signals this is for retrieving a known proceeding, versus ptab_search_proceedings for discovery. There is no explicit when-to-use/when-not guidance or reference to alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds useful context beyond that — live data via USPTO ODP v3.0 and the pagination defaults — but says nothing about result caps, rate limits, or what a paginated response looks like.

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 two-line purpose statement is front-loaded and free of filler, and the Args block is a compact per-parameter reference. Nothing is repeated for its own sake, though the parameter lines echo the schema property names rather than adding syntax detail.

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 read-only, zero-required-parameter search endpoint whose annotations already carry the safety profile, the description supplies the query semantics, field meanings, date format, and pagination controls. The absence of return-shape detail is the only omission, and it is modest for a search tool of this type.

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 0%, so the description carries the full burden, and it largely meets it: each of the 7 params is glossed with its role, and the date fields are given a concrete format (YYYY-MM-DD) that the schema does not supply. Gaps remain — no stated maximum for limit, and no indication of how the filters combine with the free-text query.

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?

States a specific verb and resource ("Search ex parte appeal decisions") and names the data source (USPTO ODP v3.0), so an agent knows exactly what corpus is queried. However, it does not distinguish itself from the sibling ptab_search_decisions, which plausibly covers a broader decision set, leaving the agent to guess which one to pick.

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?

Usage is only implied: the word "Search" plus the appeal-scoped resource signal that this is the lookup path for ex parte appeal decisions. There is no explicit when-to-use, no condition that separates it from ptab_search_decisions or ptab_get_appeal, and no statement about whether query or an identifier is required.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds that results come live from the USPTO ODP v3.0 endpoint, implying freshness and live-network dependency, but says nothing about rate limits, result ordering, or pagination semantics beyond the offset/limit params.

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 a single sentence, followed by a clean per-parameter list with no filler. The Args block is the conventional docstring form and each line earns its place, though the formatting is slightly mechanical.

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 an 8-parameter search with no output schema and no annotations gaps, the description covers inputs adequately but never describes what a returned decision record contains or how pagination should be driven. An agent knows how to call it but not fully what to expect back.

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 0%, so the description carries the full load, and it does document all eight parameters with meaning beyond the bare titles ('Full-text search in decision text', date format YYYY-MM-DD, decision_type examples institution/final/termination). It stops short of clarifying offset/limit interaction or match semantics for query, so it is solid but not exhaustive.

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 gives a specific verb+resource ('Search PTAB trial decisions'), which clearly distinguishes it from single-record siblings like ptab_get_decision or ptab_get_documents. It does not, however, explicitly contrast itself with ptab_search_proceedings or the other PTAB search tools.

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 offers no when-to-use context, no prerequisites, and no named alternatives. 'Live via USPTO ODP v3.0' is provenance, not guidance on when this search should be chosen over ptab_search_proceedings or ptab_get_decision.

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

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

Annotations already declare the full safety profile (readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false). The description adds provenance ('Live via USPTO ODP v3.0') and trial-type semantics, which is useful, but says nothing about rate limits, auth, pagination behavior, or result shape beyond a one-line 'Returns' note. Net behavioral addition is modest.

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?

Front-loaded with the core action, then organized under Trial types / Args / Returns headers. It is somewhat long because the Args block restates every schema parameter, but each line adds a short clarifying gloss, so little is wasted.

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 nine-optional-parameter search tool with no output schema, the definition covers the domain (trial types), the trigger condition, every parameter, and a brief return summary. Only pagination semantics and result-field detail are thin, which is a minor gap given the low-stakes read-only nature.

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 0%, so the description carries the full burden and mostly meets it: it defines all nine parameters, supplies the status enum values (Pending, Instituted, Terminated, FWD Entered) that the schema lacks, gives the YYYY-MM-DD date format, and states offset/limit defaults. Explanations are terse but genuinely compensate for the empty 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?

States a specific verb ('Search') and resource ('PTAB trial proceedings') and enumerates the four trial types (IPR, PGR, CBM, DER), so an agent knows exactly what domain this covers. It is clearly distinguishable from siblings like ptab_get_proceeding or ptab_search_decisions by the 'proceedings' resource, but it never explicitly contrasts itself with those search 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?

The 'USE THIS TOOL WHEN: You need to find patent validity challenges at the Patent Trial and Appeal Board' line gives a clear trigger condition. However, it names no alternatives and no when-not-to-use case (e.g., vs ptab_search_decisions or ptab_search_appeals), so routing between the search siblings is left to inference.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds the valuable behavioral fact that this returns an index record rather than live status, implying potential staleness — a meaningful distinction. It stops short of stating refresh cadence, caching, or error behavior for unknown serial numbers.

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?

Front-loaded purpose sentence followed by clear USE WHEN and Args sections; no wasted words. The Returns line ('Normalized response with the trademark record.') is thin filler that adds little, keeping it from a 5.

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 single-parameter read tool with no output schema, the description covers purpose, routing, and the one parameter's format. The return-value description is vague, but with annotations carrying the safety profile and only one input, nothing critical to correct invocation is missing.

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 0% (serial_number has no description in the schema), so the description must carry the load — and it does, specifying 8-digit application serial number with a concrete example ('78787878'). That format detail is exactly what the schema omits.

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?

States a specific verb (get), resource (trademark search-index record), and retrieval key (serial number). It also distinguishes itself from tsdr_get_trademark_status by labeling itself the 'search-index record' and the other the authoritative live status.

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?

An explicit 'USE THIS TOOL WHEN' clause gives the trigger condition (you have a serial number from tm_search_trademarks results), and it names the alternative (tsdr_get_trademark_status) with the condition that selects it (authoritative live status). No inference required.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered; the description adds genuinely new behavior: the 1955–present coverage window, that no API key is required, and the critical constraint that at least one filter is required with filters ANDed together. It still says nothing about rate limits, result caps, or failure modes, so it stops short of a 5.

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?

Front-loaded with purpose and usage in the first three lines, then cleanly sectioned Args/Returns. Every line adds information an agent needs; the parameter list is not a restatement of the schema since those fields have zero descriptions in 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?

With no output schema, the description compensates with a Returns block describing the normalized record shape (reel/frame, assignors, assignees, conveyance, affected properties). Combined with the required-filter rule and full parameter coverage, an agent has everything needed to call 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?

Schema description coverage is 0%, so the description carries the full burden — and it does: all seven parameters are documented, including the non-obvious semantics that assignee_name is the new owner and assignor_name the previous owner, a concrete reel_frame format example ('9006/0093'), and pagination defaults for offset/limit.

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?

States a precise verb and resource ('Search recorded trademark assignment (ownership transfer) records') and disambiguates the legal meaning of 'assignment' with a parenthetical. The scope statement (recorded assignments 1955–present via USPTO Assignment Center) lets an agent separate it from the patent-side assignment siblings without opening the schema.

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 'USE THIS TOOL WHEN' block gives three concrete scenarios (trace ownership history, find current owner, find marks transferred to/from a company), which is clear positive guidance. However, it names no alternative tool and gives no when-not conditions, so routing decisions against siblings like tm_search_trademarks are left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the description goes further with genuinely non-obvious context: the backend is an undocumented internal API behind tmsearch.uspto.gov with real risk of breaking without notice, plus the federal-only scope boundary. It stops short of disclosing pagination behavior or rate limits, so not a 5.

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?

Front-loads the purpose, then routes with a labeled WHEN block, a NOTE on risk, and a Args list where every line earns its place. The Args section is repetitive in prefixing each name, but the content is dense rather than padded.

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 9-parameter search tool with no output schema, all inputs are documented and alternatives are named. The Returns block is thin ('Normalized response with matching trademark records') and says nothing about pagination semantics or result shape, which is the one meaningful gap since no output schema exists to compensate.

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 0%, so the description carries the full burden and does it well: every one of the 9 parameters is explained with meaning and examples (mark_text "ACME", international_class 1-45 with "9" for software, status_filter's live/dead/omit values). It adds value the schema cannot, such as 'athletic footwear' being useful for clearance searches across wording, and limit's default 25 / max 100.

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?

States a specific verb and resource ('Search US federal trademark applications and registrations') and immediately scopes it to federal marks only. This clearly separates it from tsdr_get_trademark_status (authoritative single-mark status) and tm_get_trademark without opening either schema.

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 'USE THIS TOOL WHEN' block names concrete scenarios (clearance/knockout searches, portfolio mapping) and routes the agent elsewhere for the authoritative-status case ('use tsdr_get_trademark_status') and for class lookup ('use get_trademark_class_info'). It also states an exclusion: no common-law or state marks, only federal.

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

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

Annotations already establish read-only/idempotent/non-destructive, and the description adds real operational constraints on top: a 4-requests-per-minute rate limit, an unfiltered-wrapper size ceiling of ~10 MB, and a hard RESPONSE_TOO_LARGE rejection above 4 MB. That is the kind of behavioral context annotations cannot express.

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?

Well front-loaded: purpose first, then the when-to-use block, then the critical limits, then args. The args/returns sections partially restate the schema, which adds some redundancy, but the operational caveats earn their space.

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 no output schema present, the description still tells the agent the return shape ('Dictionary with base64-encoded PDF data') and covers the workflow, rate limit, and size-failure mode. Nothing needed to invoke this correctly is missing.

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 0%, so the description carries the full param burden and does so: serial_number is documented as 8-digit with an example ('78787878'), document_type is given concrete filter codes ('OOA', 'SPE'), and both date params specify the YYYY-MM-DD format. Far more than the type-only schema provides.

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 + output format: 'Download the prosecution document bundle for a trademark as PDF (base64)'. This is clearly distinct from sibling reads like tsdr_list_trademark_documents (list) and tsdr_get_trademark_status (status), so an agent can select it without opening any schema.

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?

An explicit 'USE THIS TOOL WHEN' block names the triggering need (office actions, responses, specimens, file-wrapper documents) and routes the agent through a prerequisite: 'Call tsdr_list_trademark_documents first, then filter by document_type and/or date range.' Both the when and the alternative are stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld, so the safety profile is covered. The description adds the genuinely useful behavioral fact that the payload is a base64-encoded image rather than a URL or rendered file, which an agent must know to handle the result; it says nothing about rate limits or what happens when no image exists.

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?

Front-loaded purpose sentence followed by clearly labelled USE THIS TOOL WHEN / Args / Returns sections, with no filler. The only minor redundancy is restating 'base64' in the Returns line already implied by the opening 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?

There is no output schema, so the description correctly steps in to describe the return shape (dictionary with base64 image data). Combined with the single required parameter being fully specified, an agent has what it needs; only edge cases (missing image, non-image marks) are unaddressed.

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 0% and the schema only says 'Serial Number' as an unannotated string, so the description carries the burden. It supplies the required format and an example ('8-digit application serial number, e.g., "78787878"'), which is exactly the missing guidance, though it does not say what happens with a malformed number.

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?

States a specific verb and resource ('Get the mark image (drawing) for a trademark as base64') and sharpens it with the qualifier 'design mark or stylized word mark'. This clearly separates it from the text-oriented siblings like tsdr_get_trademark_status or tsdr_list_trademark_documents without needing to name them.

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 'USE THIS TOOL WHEN' block gives an explicit positive trigger (need the visual representation of a design/stylized mark). It does not name a contrasting alternative (e.g., tm_get_trademark for textual mark data) or state when the tool is unnecessary, so it stops just short of full routing guidance.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds real value beyond them: the API-key requirement and the exactly-one-of constraint on the two identifiers. It does not cover error behavior, throttling, or data freshness beyond 'live'.

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?

Front-loaded imperative sentence followed by a usage block, the exclusivity constraint, and clearly labeled Args/Returns sections. No sentence is redundant; each line adds an actionable constraint or format detail.

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 two-parameter read-only lookup with rich annotations and no output schema, the definition covers purpose, trigger, auth, input format, and input constraint adequately. The Returns section is thin ('Normalized response with the trademark status record'), but the missing field detail is largely recoverable from the field list in the usage block.

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 0% and both params are nullable with no required flag, so the description carries the full burden — and it delivers: it documents each identifier with format hints ('8-digit application serial number'), worked examples, and the critical exclusivity rule that exactly one must be supplied. That rule is invisible in the schema and would otherwise cause wrong calls.

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?

States a specific verb+resource ('Get current status of a trademark application or registration') and names the source system (TSDR). It positions itself as the 'official USPTO status source,' which implies differentiation from search-oriented siblings, but never explicitly names an alternative like tm_get_trademark or tsdr_get_trademark_image.

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 'USE THIS TOOL WHEN' block gives clear triggering context — you hold a serial or registration number and need authoritative live status, owner, classes, or prosecution stage. It also flags the API-key requirement. However, there is no 'when not to use' or explicit routing to sibling tools when the need is an image, search, or document list.

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

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

Annotations already declare readOnly/idempotent/non-destructive. The description adds genuinely non-obvious context: metadata only, no downloads, and critically that it is NOT subject to the 4 req/min PDF rate limit that constrains the sibling. Pagination behavior is not stated, keeping it short of a 5.

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?

Front-loaded with purpose, then a clearly delineated usage block, args, and returns. Every sentence carries information; nothing is padding for a tool of this simplicity.

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 read-only metadata list with one required param, the description covers purpose, routing, rate-limit caveat, parameter format, and the shape of the return ('type, description, dates') despite the absence of an output schema. Nothing an agent needs to call it correctly is missing.

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 0% and the single parameter is undocumented in the schema, so the description must carry the load. It does: format ('8-digit application serial number') plus a concrete example ('78787878'), which is what an agent needs to invoke correctly.

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?

States a specific verb and resource ('List prosecution document metadata for a trademark') and immediately scopes it with '(no downloads)'. This distinguishes it cleanly from the sibling tsdr_download_trademark_documents without requiring the agent to open either schema.

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 'USE THIS TOOL WHEN' section names the exact scenario (see what file-wrapper documents exist before downloading) and names the alternative tool it is not. It further explains how its output feeds the download tool's document_type filter, closing the loop between the two tools.