GleanMark Trademark Search

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

Annotations are all false (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), so the description carries the burden. It discloses two important behaviors: it is asynchronous for authenticated users and returns a processing handle. These go beyond annotations and are useful for an agent to know. However, it does not explicitly state whether the operation is read-only or has side effects, though 'analyze' implies safety.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with zero filler. The core purpose is front-loaded, and the async behavior and handle are clearly stated. 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 explains the immediate return (a processing handle) but does not describe the final result's format. It does describe the scope of the analysis (timeline, examiner patterns, etc.), which gives a good sense of what will be produced. It also mentions the authentication requirement and async nature, which are essential for correct invocation. Minor gap: no mention of how to retrieve the result once ready, but that may be covered by another 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?

There is only one parameter, serial_number, and the schema description covers it as 'USPTO serial number' (100% coverage). The description adds no further meaning about the parameter, so it does not exceed the schema's baseline. Per the rubric, a baseline of 3 is appropriate when schema coverage is high and the description does not add parameter-specific detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool analyzes the full prosecution history of a trademark, listing specific components (narrative timeline, office actions, responses, examiner decisions, status, examiner-behavior patterns). This is a specific verb+resource and distinguishes it from siblings like get_prosecution_timeline (timeline only) and get_mark_prosecution_summary (summary).

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 mentions that it is for authenticated users and launches asynchronously, which is a usage condition, but it does not provide explicit guidance on when to use this tool versus alternatives such as get_prosecution_timeline or get_mark_prosecution_summary. It implies this is a deeper analysis but never states exclusions or the alternative use cases.

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?

The description discloses a significant behavioral trait: asynchronous execution for authenticated full-mode runs (1-2 minutes) and the need to retrieve a processing handle. This goes beyond the annotations, which only state readOnlyHint=false and destructiveHint=false. It adds practical context for agent invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, both informative. The first sentence states purpose and outputs; the second covers the async caveat. No wasted words, and critical details are front-loaded.

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 description covers the output summary, async behavior, and timing, which is sufficient for a call. However, it leaves ambiguity about non-authenticated runs (only 'authenticated full-mode' is mentioned) and does not describe what the processing handle looks like. Minor gaps for a tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (both quick_mode and proceeding_number have descriptions). The tool description does not add parameter-level meaning beyond the schema, so the baseline score of 3 applies.

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 uses a specific verb-resource pair ('Analyze a TTAB proceeding in depth') and enumerates concrete outputs (structured summary, timeline, party positions, strategic assessment). It clearly differentiates from sibling tools like get_ttab_proceeding_details, which presumably provide raw details rather than analysis.

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 case is implied (in-depth analysis of a TTAB proceeding), but the description never mentions sibling alternatives or conditions for using this tool versus get_ttab_proceeding_details or search_ttab_proceedings. No exclusions are provided, so guidance remains vague.

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. The description adds significant context beyond those: it explains that the tool returns a screening tier and top conflicts, qualifies results as open-world ('none surfaced, not available'), and explicitly lists what the tool does not cover. This aligns with and enriches the annotations without contradiction.

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 sentences with no filler. The first sentence front-loads the purpose and output, the second defines scope and interpretation, and the third points to the alternative. Every sentence earns its place, and the structure is perfectly 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 explicitly specifies return values (screening tier with named options, top conflicts, domain snapshot). It also covers the open-world interpretation and the boundary with run_knockout_search, giving an agent everything needed to call the tool correctly and interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds context that industries/classes are used for the trademark screen, but it does not provide additional semantics for brand_name or business_description beyond what the schema already states. It doesn't introduce new parameter-level guidance, so a 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb+resource ('brand-name screen') and enumerates exactly what it does: checks domain registration, .com site usage, and similar trademarks, and returns a screening tier with top conflicts and a domain snapshot. It also differentiates from run_knockout_search by calling it the fuller search, making the tool's distinct role 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?

The description explicitly states when to use the tool ('first look') and when not to rely on it ('not a clearance search'), lists the specific omissions (common-law use, state registrations, goods-relatedness), and warns that no conflicts does not mean availability. It names run_knockout_search as the alternative for deeper conflict analysis, leaving no ambiguity.

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 operation read-only, open-world, and idempotent; the description adds meaningful behavioral detail by enumerating the possible statuses and the inclusion of .com variations. This goes beyond the annotation-only baseline without contradicting it.

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 a compact two-sentence definition with no filler. The core purpose is front-loaded and the added return detail is essential and concise.

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 lookup tool with fully documented parameters and no output schema, the description covers both input scope and output shape. Nothing critical is missing for an agent to invoke 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 100%, with both brand_name and tlds already documented. The description adds no extra parameter-level semantics beyond what the schema provides, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Check') and the resource ('domain availability for a brand name'), and it enumerates the output statuses and .com variations. It is specific enough to distinguish from sibling tools like check_brand_availability.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool: whenever an agent needs to check domain availability for a brand. However, it provides no explicit guidance on when not to use it or how it relates to sibling tools such as check_brand_availability.

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 and idempotentHint=true, covering safety. The description adds the behavioral detail of returning similarity scores and risk assessment based on DuPont factors, which is useful context. It does not describe any hidden side effects or limitations, but with annotations handling safety, a score of 3 is appropriate—credit for the methodological hint, but no contradiction.

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 short sentences: the first front-loads the action and scope, the second summarizes the output. It contains zero filler and every word contributes meaning. Perfectly sized for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity, an output schema exists (covering return values), and annotations cover safety, the description is largely complete. It states the purpose, methodology, and output type. Minor omissions include explicit guidance on input format for trademarks (e.g., normalized strings) and any caveats about the DuPont analysis, but these do not critically impair an agent's ability to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents each parameter. The description does not add extra meaning beyond ^^'DuPont-style analysis'^^, which hints at how the parameters are used together. Since the schema carries the load, a baseline 3 is correct; the description adds no new semantics for the parameters themselves.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Compare' and the resource 'trademarks', with a specific purpose ('likelihood of confusion') and methodology ('DuPont-style analysis'). It also indicates the output ('similarity scores and risk assessment'), distinguishing it from sibling tools like 'get_similar_marks' (which likely fetches similar marks for one mark) and 'check_brand_availability' (which checks availability, not confusion).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: when you have two trademarks and want to assess confusion risk, use this tool. However, it does not explicitly state when not to use it or mention alternatives, relying on the agent to infer from the tool's distinct purpose. No clear exclusion conditions or named alternatives like 'use get_similar_marks for one-to-many searches'.

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?

Beyond the readOnly/idempotent annotations, the description discloses the counting methodology (one per serial number by filing date), the scope distinction from fiscal-year statistics, and the data freshness caveat that recent periods grow as late records arrive. This gives the agent important expectations about result stability and interpretation.

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 somewhat long but well structured: core behavior first, example questions second, caveats last. Every sentence carries useful information, and the most important scoping statement is front-loaded, though the first sentence is dense and could be split.

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 aggregate tool with no output schema, the description covers the return concept (periods, splits, change, data_through), counting rules, and data freshness. It doesn't detail the exact output shape, but it provides enough about return semantics for an agent to invoke and interpret the result correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics: counts are based on filing date on the USPTO record, daily grouping covers at most about a year, and the meaning of returned periods is clarified. This goes beyond the schema's date-format and enum descriptions.

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?

Description states a precise action and resource: counts U.S. trademark applications across the whole register within a date range, grouped by year/month/day. It distinguishes itself from attribute-based counting by explicitly saying it is not class counts and covers the whole register, so an agent can tell it apart from siblings like count_trademarks_by_attributes.

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?

Gives concrete example questions ('how many trademark applications were filed in 2025 and how that compares with 2024') and clear scope constraints: whole register, calendar periods, not USPTO fiscal-year statistics, not class counts. It does not name an alternative tool explicitly, but the exclusions effectively route an agent away from attribute-based or fiscal-year tools.

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 meaningful behavioral context beyond annotations: it previews results, provides breakdowns by mark type/standard character/class, reports data completeness, and supports combining claimed-color criteria with attributes. It also clarifies that color-alone counts are out of scope, which is a behavioral boundary not visible in the schema. Minor gap: it doesn't describe pagination or the exact shape of the preview, but the annotations carry the safety burden.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The first sentence front-loads the core function (counts/previews by attributes) and the breakdowns, and the second sentence adds the color-combination capability and scope exclusions. Every clause earns its place, and the scope exclusion is concise rather than verbose.

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 analytics tool with 9 optional parameters and no output schema, the description covers the core purpose, the attribute dimensions, the breakdowns, data-completeness reporting, and scope exclusions. It doesn't describe the return format or pagination, but since there is no output schema, a brief note on what the preview contains would strengthen it. The annotations cover safety, and the parameter semantics are mostly inferable from the schema enums and defaults. Overall, it's nearly complete for an agent to decide whether to invoke it.

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 only 44%, so the description must compensate for undocumented parameters. The description adds meaning by explaining that attributes (drawing type, standard-character claim, Nice class, status) can be combined, and that claimed-color criteria can be combined with these attributes. It also clarifies the scope of color parameters (exact canonical shades vs normalized families) indirectly. However, it doesn't explain the semantics of class_match_mode, color_match_mode, or limit beyond what the schema already provides, and it doesn't detail how the parameters map to the breakdowns.

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 ('Counts and previews'), a clear resource (USPTO marks by record attributes), and enumerates the exact attribute dimensions (drawing type, standard-character claim, Nice class, status) plus combinations. It also explicitly names what is outside its scope (color-alone counts, rankings, lists, color vocabulary), which distinguishes it from siblings like search_claimed_colors and count_filings_by_period.

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 clearly implies when to use this tool: when the agent needs aggregate counts/previews of USPTO marks filtered by record attributes, with breakdowns. It explicitly excludes color-alone counts, rankings, lists, and color vocabulary, which routes the agent away from this tool for those needs. However, it does not name specific sibling alternatives (e.g., search_claimed_colors, count_filings_by_period) or state explicit when-not-to-use conditions beyond the scope 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavior beyond annotations: it lists the specific fields returned (mark, owner, status, dates, Nice classes, goods/services, counsel) and notes the public gleanmark.com citation URL. This provides useful context without contradicting 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?

A single, well-structured sentence that front-loads the core purpose, then lists return contents. No filler or redundant phrasing. Every clause adds value.

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 retrieval tool with no output schema, the description fully covers what an agent needs to know: what to pass, what it returns, and a citation URL. Combined with annotations covering safety, nothing critical 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 100% and already explains the id parameter thoroughly, including format and example. The description's mention of 'using an id returned by the search tool' reinforces but does not substantially expand beyond the schema. Baseline 3 is appropriate since the schema handles the parameter semantics.

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 ('Retrieve'), a precise resource ('full USPTO record for one trademark'), and the input source ('id returned by the search tool'). Clearly distinguishes itself from sibling tools like search or lookup_trademark by focusing on a single record retrieval with a given id.

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?

Explicitly states when to use it: 'using an id returned by the search tool.' This provides a clear precondition but does not name alternative tools for other scenarios (e.g., if only a serial number is known, one might need search first). The guidance is contextually clear but not exhaustive.

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 description adds value beyond those. It discloses meaningful behavioral details: the data comes from USPTO-recorded ownership stages plus GleanMark-held assignment documents, joint owners within one stage are not successive owners, and the result is not a title opinion. A minor omission is the lack of a response-shape example, but that is not critical for a read-only chain-of-title lookup.

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 compact and front-loaded with the core function. Each sentence earns its place: scope of the trace, the types of questions answered, the sibling contrast, the joint-owner caveat, and the not-a-title-opinion disclaimer. There is no filler or redundant restatement of the tool name.

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-required-parameter, read-only tool with a fully described schema and strong annotations, this description is complete. It explains what data will be returned, how to interpret ownership stages, and when to use an alternative tool. Even without an output schema, the explicit enumeration of returned content compensates adequately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the serial_number parameter already has a detailed description including format, an example, and the explicit exclusion of registration numbers. The tool description itself adds no parameter-specific semantics, but the schema fully carries that burden, so the baseline 3 applies.

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 uses a specific verb ('traces') with a clear resource (trademark ownership history) and enumerates concrete outputs: ownership stages, assignment documents, and answers to due-diligence questions. It explicitly contrasts with lookup_trademark, which shows only current ownership, so an agent can distinguish this tool from its closest sibling. The 'Not a title opinion' caveat further sharpens what the tool does and does not deliver.

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 explicitly tells the agent when to use this tool versus lookup_trademark: use this for ownership history and chain-of-title questions, and use lookup_trademark when only the current owner is needed. The parameter description also directs the agent to resolve a serial number first with lookup_trademark or search_trademarks, since registration numbers are not accepted. This is clear when-to-use and when-not-to-use 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, and destructiveHint=false, so the safety profile is covered. The description adds no extra behavioral context such as pagination, rate limits, or response format. It is consistent with annotations but adds nothing beyond them.

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 a single, efficient sentence that conveys the core purpose without fluff. It is front-loaded and every word earns its place, making it highly concise.

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 tool has 4 parameters and no output schema, so the description carries more burden. It fails to explain the semantic difference between 'coordinated' and 'related' classes, which is critical for choosing the right relationship_type. It also does not clarify what the response looks like or what happens when optional parameters are omitted. This is a significant gap for an agent to call the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters are documented in the schema. The description adds minimal value by mentioning 'coordinated' and 'related' which map to the relationship_type enum, but it does not elaborate on limit, include_legacy, or defaults. Baseline of 3 is appropriate since the schema carries the meaning.

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 clear verb ('Look up') and a specific resource (coordinated/related Nice classes for a given class number). It distinguishes between two types of relationships but does not explicitly contrast it with sibling tools like get_nice_classes or recommend_nice_classes, so it misses the explicit differentiation that would earn 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?

There is no guidance on when to use this tool versus alternatives. No mention of when to prefer this over get_nice_classes or recommend_nice_classes, nor any exclusions or prerequisites. The agent is left to infer usage context from the name alone.

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 behavior. The description adds meaningful behavioral detail beyond that: sampling up to max_sample from the start of the window, disclosure of truncation, and the group-selection mechanism via anchor events and date windows. It does not contradict any annotation and gives the agent a realistic picture of how results are produced.

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 four dense sentences with no filler; the main purpose and example lead, followed by selection logic, output summary, and sampling behavior. It packs substantial information into a compact space, though a slightly more explicit break between concepts could improve scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 9 parameters, full schema coverage, and no output schema, the description covers the essential gaps: what the output contains (average, median, percentiles, count of no-start-event marks, examples), sampling/truncation, and the 366-day window cap. It does not detail the exact response structure, but the listed metrics are sufficient for an agent to invoke and interpret results.

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 100% schema description coverage, the baseline is 3, and this description adds value beyond the schema by explaining the conceptual roles of anchor event, start event, and end event, as well as the wildcard semantics for raw event codes. It also clarifies the relationship between sampling and the date window, which the schema does not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Measures the time between two prosecution events across a group of marks.' It provides a concrete example (average days from Office Action to publication for Q2 2026) and enumerates anchor event presets. This clearly distinguishes it from per-mark tools like get_prosecution_timeline or get_mark_prosecution_summary.

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 intended use is implied by the description: aggregate cohort interval statistics. It explains cohort selection, window constraints, and event code flexibility, but it never explicitly says when to prefer this tool over siblings or when not to use it. The only cross-reference is to get_event_code_reference for event codes, which is auxiliary rather than usage direction.

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 readOnly, idempotent, and non-destructive behavior, so the bar is lowered. The description adds meaningful context beyond annotations: it returns marks sorted by prosecution history length and includes event counts and office action flags. It doesn't fully disclose the meaning of 'office action flags' or any nuances of the sort, but it does add behavioral value beyond what annotations 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?

The description is two concise sentences with no filler. The core functionality is front-loaded ('Get all trademarks handled by a specific attorney/correspondent'), followed by return details and a usage hint. Every sentence earns its place, and it is appropriately brief for a query 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?

The tool has 7 optional parameters and no output schema. The description covers the core function and return characteristics, and the schema provides full parameter documentation. However, it does not address how to choose among the redundant correspondent identifiers (search_term vs correspondent_name vs correspondent_id vs canonical_correspondent_id), which could confuse an agent. That small gap prevents a perfect score, but overall it is sufficiently complete for a read-only query tool with annotations.

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 schema description coverage is 100%, so baselines at 3. The description does not elaborate on parameter semantics beyond what the schema already provides. For instance, it mentions 'attorney-specific mark queries' but does not explain the multiple alias parameters (search_term, correspondent_id, correspondent_name, canonical_correspondent_id). Since the schema fully documents each parameter, the description adds minimal extra value 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?

The description states a specific verb and resource: 'Get all trademarks handled by a specific attorney/correspondent'. It also names the key features (prosecution event counts and office action flags) and the sorting order. This clearly distinguishes it from sibling tools like get_correspondent_specialization or get_firm_correspondent_tasks, which focus on different aspects.

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 explicitly says 'Use this for attorney-specific mark queries', which gives clear context on when to invoke it. However, it does not mention alternatives or conditions when not to use it, such as when the user wants marks by owner or firm rather than a specific correspondent. That lack of exclusions keeps it at a 4 rather than 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 convey readOnlyHint, idempotentHint, and destructiveHint. The description adds useful behavioral context by detailing the summary content: top clients, top Nice classes, and prosecution-versus-TTAB profile. This goes beyond the annotation-only signal and gives the agent a clearer picture of what the tool will produce.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no redundant filler. The core action and output contents are front-loaded, and the usage trigger is appended efficiently. Every sentence contributes to selecting and invoking the tool correctly.

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?

Combined with a fully described schema and an output schema, the description provides enough context for correct invocation. The only minor gap is the lack of explicit guidance on which identifier parameter to prefer or how resolution behaves, but this is not critical given the schema covers parameter descriptions and the output schema explains return structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents every parameter. The description adds only high-level context ('named correspondent') and does not explain the relationship between url_key, search_term, and correspondent_name, nor the effect of the limit parameters. This is adequate but not additive beyond the schema baseline.

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 uses a specific verb and resource: 'Summarize what a named correspondent specializes in.' It also enumerates the output categories (top clients, top Nice classes, prosecution-versus TTAB profile) and clearly distinguishes this from related correspondent tools by framing it around specialization rather than marks or firm-level tasks.

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 explicitly says when to use the tool: 'Use this when the user asks what a specific correspondent or attorney specializes in.' It does not name alternatives or exclusions, but the stated trigger condition is clear enough for an agent to select it over siblings like get_correspondent_marks or search_attorneys.

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 safe lookup nature is covered. The description adds useful context by naming the specific table (deadline_event_roles) and the closed vocabulary scope, but does not address edge cases like unknown event codes or missing mappings.

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?

One dense, front-loaded sentence with no filler. It conveys the action, the domain table, the possible roles, and the deadline families in a compact format.

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 two-parameter read-only lookup with rich annotations, the description is nearly sufficient. It names the role outcomes and deadline categories, though it leaves the exact return shape unspecified since there is no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description restates the parameter concepts and adds grouped examples of deadline types, but it does not meaningfully extend the schema's parameter documentation.

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 uses a specific verb ('Check') and a precise resource (the role of a USPTO event code for a deadline type) and enumerates the exact role outcomes: satisfies, triggers, abandons, suspends. It is clearly distinct from sibling lookup tools like get_event_status_mapping because it is anchored to the deadline_event_roles vocabulary table.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context: this is a reference lookup for event-code-to-deadline-type relationships. It does not explicitly name alternatives or when-not-to-use conditions, but the deadline vocabulary framing makes the intended use 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 and destructiveHint=false, so the tool is known to be a safe read operation. The description adds useful behavioral detail beyond annotations: the search modes (exact, prefix, keyword) and the return content (code, description, category). This is more than the typical annotation-covered case, though it omits edge behavior like empty-result handling or no-parameter calls.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the primary verb and resource. Every clause contributes: what it looks up, how to search, and what it returns. No filler or repetition.

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 appropriately explains the return fields. However, it does not clarify behavior when no parameters are provided (all are optional in schema), nor does it mention pagination or default search behavior beyond the limit parameter. This ambiguity could cause an agent to assume a search term is required, making the description incomplete for a tool with zero required parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description mostly restates what the schema already says about code and search. It adds minimal value by framing them as alternative search modes, but does not meaningfully supplement the parameter meanings beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool's resource (USPTO event codes used in trademark prosecution) and its specific actions: look up by exact code, prefix, or keyword. It also names the return fields, making it distinct from sibling tools like get_event_status_mapping or get_reference_lookup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool (when you need to look up or decode USPTO event codes) but provides no explicit guidance on when not to use it or which alternative sibling might be more appropriate (e.g., get_event_status_mapping for status mapping). With many siblings available, this is a clear gap.

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 nuance that results reflect 'most commonly' following statuses, implying an aggregate/probabilistic mapping rather than a guaranteed exact match. This adds value but doesn't go deeper into output 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?

The description is a single, front-loaded sentence with zero filler. It communicates the action, the resource, and the qualifying logic in under 20 words while remaining easy to parse.

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 two-parameter, read-only lookup, the description plus fully documented schema is largely sufficient for an agent to call it correctly. It doesn't describe alternatives or explicit output format, but it does indicate what is returned (status code and definition). The lack of an output schema is partially compensated by the description's clarity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters are adequately documented in the schema itself. The description does not add meaning beyond what the schema provides for event_code or limit, so the baseline score of 3 applies.

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 uses a specific verb ('Look up') and resource ('USPTO status code and status definition') with a clear qualifier ('most commonly follow a specific prosecution event code'). It conveys a distinctive statistical-mapping function, though it does not explicitly differentiate itself from sibling tools like get_event_code_reference. The title is generic but the description is specific enough.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies its use case: when an agent needs the most likely status code/definition for a given prosecution event code. However, it provides no explicit when-to-use, when-not-to-use, or alternative tools, which matters given many similar siblings exist. It is sufficient for an obvious lookup intent but lacks 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, and destructiveHint=false, so safety is covered. The description adds value by clarifying that the output is circumstantial (not statutory proof) and by listing what the profile contains, which helps the agent interpret results. It doesn't mention performance, caching, or data sources, but with annotations covering the safety profile, this is adequate. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is information-dense but well-structured: it leads with the core purpose and output components, then adds usage context and a caveat. Each sentence earns its place; nothing is wasted. It is slightly long but not bloated, and the most critical information (what the tool returns) is front-loaded. A 4 is warranted for its efficiency.

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 carries the full burden of explaining what the agent will receive. It enumerates all major components (fame tier, path, class footprint, portfolio size, crowding, TTAB history) and clarifies the evidential weight. It also provides usage context and the parameter behavior. For a tool of this complexity, the description is complete and leaves no critical gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single parameter mark_or_stem, with a clear explanation that it accepts either a full mark or a brand stem. The description repeats this concept but does not add any new semantic detail beyond the schema. Since the schema fully documents the parameter, the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb ('Get') and a clearly defined resource ('full fame profile for a brand'), then enumerates the specific components returned (fame tier, path, class footprint, portfolio size, crowding, TTAB history). It explicitly distinguishes itself from the sibling is_mark_famous by implying this provides a detailed profile rather than a simple yes/no answer, and it adds a caveat about circumstantial vs statutory proof. The 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?

The description states concrete use cases: 'explain WHY a mark is (or is not) famous' and 'profile a senior mark before a §2(d) / opposition / dilution strategy.' It also warns that the output is 'circumstantial signal, not statutory fame proof,' which guides appropriate reliance. It does not explicitly name alternatives like is_mark_famous for quick fame checks, but the context makes the intended use clear. This is strong guidance, slightly short of naming when-not-to-use alternatives explicitly.

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 meaningful detail about the contents (flags, time windows, source of OAs), but does not disclose any additional behavioral aspects such as data freshness, pagination, or how firm resolution works. It adds some context beyond annotations but not extensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with zero fluff. It front-loads the core function and the components of the return, then gives concrete examples of questions it answers. Every sentence adds value and the structure is 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 tool that combines deadlines and Office Actions, the description adequately explains both components and the flags. It does not describe the return format, but there is no output schema and the description covers the essential content. Minor gaps include not specifying how 'recent' is defined (though the deadline_days and recent_oa_days params handle this) and not mentioning any limitations on firm resolution. Overall, it is sufficiently complete for an agent to use 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 coverage is 100%, so parameters are fully documented in the input schema. The description adds a bit of context by explaining what 'action-required' means and giving example queries, but it does not elaborate on parameter semantics beyond what the schema already provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('resolves') and clearly identifies the resource (trademark law firm's action-required work). It enumerates exactly what is returned—overdue deadlines, next-window deadlines, recent Office Actions, and flags for filed responses and Section 2(d) refusals—which distinguishes it from siblings like get_firm_deadlines or get_latest_office_action that handle only subsets of this data.

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 provides clear context on what the tool answers ('which correspondent tasks a firm has in the next 30 days') and implicitly signals its combined scope, but it does not explicitly name alternative tools or state when to prefer this one over others like get_firm_deadlines or get_firm_oa_outcomes. The usage intent is clear, but exclusions are absent.

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, covering the safety profile. The description adds value beyond that by disclosing the data source ('Uses public firm resolution and prosecution mappings only') and explicitly excluding workspace, client, reminder, or user-created deadlines. This gives an agent a clear picture of what is and isn't included without contradicting 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 sentences, zero filler. The first sentence front-loads the core purpose, and the second adds the critical scope limitation. Every word earns its place; no redundant phrases or restatement of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (7 params, 1 required) and the presence of an output schema, the description covers the essential purpose and data scope. It does not mention pagination, firm resolution failure behavior, or edge cases, but those are secondary given the output schema and annotations. The description is adequate for an agent to decide when to call it and what to expect.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% — every parameter (firm_name, limit, days_back, days_ahead, status_filter, include_opposition_period, include_informational_windows) has a meaningful description. The tool description itself does not add any parameter-specific semantics beyond what the schema already provides. Per the rubric, the baseline of 3 applies when the schema fully documents parameters.

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 ('Get') and resource ('public, system-generated trademark deadlines across marks handled by a specific law firm'). It clearly distinguishes this from sibling deadline tools like get_mark_deadlines (single mark) and get_owner_deadlines (owner) by anchoring on firm-level aggregation. The phrase 'Does not expose any workspace, client, reminder, or user-created deadline data' further sharpens the scope.

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 provides clear context: it is for firm-level deadlines, public and system-generated only. This implies when to use it (aggregate deadlines across a firm's marks) but does not explicitly name alternatives or state when not to use it. There is no mention of 'use get_mark_deadlines for a single mark' or similar routing, so it falls short of an explicit when/when-not 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 and idempotentHint=true, covering safety. The description adds behavioral detail by clarifying the computation includes both raw rates and rates excluding pending matters, which is useful context. It does not contradict annotations and provides meaningful nuance about the output.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with zero waste. The core function is front-loaded, followed by concrete example queries that immediately ground the agent. No redundant information is present.

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 must convey what the tool returns. It mentions raw and excluding pending rates, implying counts or percentages, and the limit parameter implies examples. However, it doesn't explicitly state the structure of the returned data (e.g., buckets, examples, percentages). For a tool with moderate complexity, this is a notable gap, though not critical for basic usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both parameters (firm_name and limit) documented in the input schema. The description does not add additional meaning beyond the schema; it only references resolving a firm, which is already implied by the firm_name parameter. Per rubric, baseline 3 is appropriate when schema fully covers parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool's function: resolving a trademark law firm and computing mark-level Office Action outcome rates. It distinguishes from siblings by specifying firm-level aggregation, which is not covered by other tools like get_latest_office_action or research_office_action that operate per-mark. The verb 'resolve and compute' is specific and the resource is well-defined.

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 explicitly states when to use the tool with example queries ('what percentage registered after an OA?' or 'OA success rate for this firm'). It provides clear usage context, though it doesn't mention when not to use it or alternative tools. Since no sibling directly overlaps, the guidance is sufficient for routing.

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 readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context by disclosing the ranking order (by filing volume) and that prosecution and TTAB activity counts are included, which goes beyond the structured annotation fields. It does not overstate or contradict 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 sentences with no filler: the core behavior is front-loaded in the first clause, and the example question reinforces the intended query pattern. 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?

For a simple ranked-list tool with a fully covered input schema, rich annotations, and an output schema, the description is nearly complete. It lacks only an explicit pointer to alternative tools for related but different questions, such as a single correspondent's marks or specialization.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description confirms firm_name refers to a named law firm but does not add anything about limit or accepted key formats beyond the schema, so it neither improves nor worsens parameter clarity.

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?

Description uses a specific verb ('Ranks') and clearly identifies the resource ('correspondents or attorneys within one named law firm') and the ranking criterion ('by filing volume'). The mention of prosecution and TTAB activity counts further distinguishes it from sibling tools like get_firm_correspondent_tasks or get_top_filers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the use case with an example question ('who the top correspondents at Fross Zelnick...'), so an agent can infer when to call it. However, it gives no explicit when-to-use guidance, no exclusions, and does not compare against alternative tools such as search_attorneys or get_firm_correspondent_tasks.

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 agent knows it is a safe read operation. The description adds a meaningful behavioral nuance: refusal_grounds is parsed from the text of the action, not the document title, and the response is 'if there is one.' It does not cover edge cases (e.g., missing serial number or no office action), but the safety profile is well covered by annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, dense sentence that front-loads the primary purpose and includes necessary details about the response and refusal grounds. There is no redundant wording, but it is slightly long and could benefit from splitting into two sentences for readability. Overall it is efficient 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 tool with only one parameter and annotations covering safety, the description is fairly complete: it lists all key outputs (latest office action, latest response, refusal grounds with cited regs) and clarifies the parsing source. It does not explain what happens if no office action exists or how to handle errors, but these are minor gaps for such a simple tool. Given the absence of an output schema, the description covers the essentials.

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 schema already provides a clear description of the only parameter (serial_number: 'USPTO serial number'), achieving 100% schema description coverage. The tool description does not add any further parameter-specific semantics, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Returns') and a specific resource ('most recent Office Action for a trademark serial number'), and it additionally details the extra outputs (response and refusal grounds with cited registration numbers). This clearly distinguishes it from sibling tools like get_prosecution_document or research_office_action, which have different scopes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no explicit guidance on when to use this tool versus alternatives. It does not mention scenarios where another sibling (e.g., research_office_action for deeper analysis or get_prosecution_document for a specific document) would be more appropriate. The only implicit cue is 'most recent,' but no exclusions or alternatives are 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 (readOnlyHint=true, idempotentHint=true, destructiveHint=false). The description adds value beyond that by disclosing the output is AI-generated and synthesized, which signals non-deterministic or interpretive content, and by scoping exactly what the summary covers. No contradiction with 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 sentences with no filler. The first sentence front-loads the action and resource; the second sentence earns its place by enumerating the summary's scope. Nothing is redundant with the schema or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with one well-documented parameter, read-only annotations, and no nested objects, the description is nearly complete: it states what the tool does and what the output covers. The only gap is that no output schema exists and the description does not hint at the output format (e.g., natural-language narrative vs. structured fields), though 'deep-dive summary' strongly implies a narrative result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% — the single required parameter serial_number is already described as 'USPTO serial number'. The description adds no format, validation, or usage detail beyond the schema, so it rests at the baseline 3 for high-coverage cases.

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 an AI-generated deep-dive summary of a specific trademark') and enumerates coverage areas (mark details, goods/services, status, owner, prosecution context, legal proceedings). This implicitly separates it from focused siblings like get_mark_prosecution_summary, but it never names a sibling or draws an explicit contrast, 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?

The description implies this is the go-to high-level overview tool for a mark, and the 'Covers...' list hints at when it is appropriate. However, there is no explicit statement of when to choose it over get_mark_prosecution_summary, get_owner_ai_summary, or lookup_trademark, and no exclusions are given. Usage context is implied rather than 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 readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value by clarifying the data scope (public, system-generated) and the exclusion of workspace/client/user-created data. It does not describe edge cases like not-found behavior, but that is acceptable given 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 sentences deliver the full purpose, input modes, and exclusions without waste. The key scope is front-loaded, making it easy for an agent to parse quickly.

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 an output schema present, return format is not needed. The description covers how to specify the mark (serial or name), the data scope (public, system-generated), and what is excluded. Defaults are in the schema. It is complete for a read-only query tool, though it could mention resolution behavior in more detail if that were a common failure point.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all eight parameters are documented in the schema. The description's mention of 'resolves a mark name to a specific serial first' slightly reinforces subject_name but adds no new semantics beyond the schema. Baseline 3 is appropriate given high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool gets public, system-generated trademark deadlines for a specific mark, and specifies input modes (serial number or resolving a mark name). It distinguishes itself from sibling deadline tools (firm, owner) by explicitly noting it does not expose workspace, client, reminder, or user-created deadlines.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context: it is for public system-generated deadlines for a specific mark, and it explicitly states what it does not expose, implying when not to use it. However, it does not name alternative tools (e.g., get_firm_deadlines) directly, so it falls short of explicit when/when-not 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, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context beyond that: the data source is USPTO records, so coverage is limited to marks with USPTO records, and it is not a live query against WIPO/EUIPO. This prevents an agent from over-trusting the result or expecting real-time international 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?

The description is front-loaded with the core purpose, then lists the data fields, then the intended use case, then the data-source caveat. Every sentence adds distinct value and nothing is redundant with the schema or annotations.

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-required-parameter read-only tool with strong annotations, the description fully covers what an agent needs to know: what the tool does, what data it returns, when to use it, and its critical limitation regarding live WIPO/EUIPO data. No output schema exists, but the description enumerates the returned fields sufficiently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the only parameter, serial_number, is already described as 'USPTO serial number' in the schema. The description reinforces the context by saying 'by serial number,' but it does not add format, validation, or usage details beyond what the schema provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('Get the international / foreign footprint of a U.S. trademark by serial number') and enumerates the exact data elements returned: IR number/date/status, 66(a) extensions, Madrid maintenance, and foreign priority filings. This level of specificity clearly differentiates it from sibling mark-related tools like get_mark_deadlines or get_mark_ai_summary.

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 invocation rule: 'Use this for ANY question about a mark's foreign, international, Madrid Protocol, WIPO, or EUIPO registrations.' It also states an important limitation — data is only from USPTO records and does not query live WIPO/EUIPO — which helps an agent avoid misusing it for live international data. It does not name alternative tools, but the guidance is clear enough.

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, destructiveHint=false, idempotentHint=true, covering the safety profile. The description adds the behavioral detail that results are 'ranked by footprint' and include 'wider portfolio context,' which is useful. It does not disclose pagination or any rate limits, but given the annotations, the added context is sufficient. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, front-loads the core action ('Show which owners hold marks...') and then provides usage guidance and an example. There is zero waste; every sentence earns its place. The structure is logical: purpose first, then when to use, then what it returns.

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 tool has an output schema (context signals confirm this), so the description does not need to detail the return structure. It does state the output concept ('Returns the matching owners ranked by footprint, with each owner's wider portfolio context'), which is sufficient for an agent to understand the result. With 5 parameters, 1 required, and full schema coverage, the description is complete for a read-only landscape 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?

Schema description coverage is 100%, so all five parameters are already documented in the schema. The description adds marginal value by giving examples of mark_text ('COMET or GLOW') and mentions ranking by footprint, but it does not elaborate on individual parameter semantics beyond what the schema provides. Baseline 3 is appropriate since the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Show which owners hold marks matching a shared trademark term and summarize what else those owners have in their broader portfolios.' It uses specific verbs (show, summarize) and a specific resource (owners holding matching marks). This distinguishes it from siblings like get_similar_marks (which focuses on marks, not owners) and search (which is broader). The examples ('COMET', 'GLEAN') further clarify the scope.

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 explicitly states when to use it: 'Use this for crowded owner-landscape questions like ...' and gives concrete examples. It does not explicitly name alternatives or state when not to use it, but the purpose is clear enough that an agent can infer it is not for single-mark analysis or similarity searches. A clear 'when not to use' clause is missing, but the provided guidance is strong.

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 destructiveHint, so the tool's safety profile is well covered. The description adds useful behavioral context by specifying exactly what the summary contains, which helps set expectations even without an output schema.

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 sentences with the action front-loaded and the returned information presented as a tight enumeration. There is no filler, redundancy, or unnecessary background.

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-parameter, read-only summary tool, the description covers the main output contents and the annotations cover safety. It does not address edge cases or serial-number formatting, but the schema and annotations already handle the critical structured context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single parameter is already described as a 'USPTO serial number.' The description only repeats this as 'trademark serial number' without adding format, normalization, or example guidance, so it meets the baseline but adds no extra semantic value.

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 uses a specific verb ('Get') and identifies the resource as a 'compact prosecution summary' for a trademark serial number. It then enumerates concrete return components (current status, document counts, dates, milestones, latest key event), which distinguishes it from siblings like get_prosecution_timeline, get_latest_office_action, and get_mark_ai_summary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for a quick overview via 'compact' and 'latest key event,' but it does not explicitly name alternatives or provide when-not-to-use guidance. An agent could infer the difference from get_prosecution_timeline or analyze_prosecution_history, but the route is not 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 readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds context about trademark registration and the two lookup modes, but it does not disclose result limits, behavior when no matches are found, or whether both parameters can be combined. No contradiction with 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 sentences with no filler. The main action and resource are front-loaded, followed immediately by the two invocation modes. 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?

For a simple read-only lookup with two optional, fully described parameters and an output schema, the description covers the essential purpose and usage modes. The only notable gap is the lack of guidance on combining or choosing between the two parameters and how the tool relates to the recommendation sibling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%: both search_term and class_numbers have detailed descriptions with examples, ranges, and length constraints. The description merely restates the two modes without adding meaning beyond the schema, so the baseline of 3 applies.

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 uses a specific verb and resource: 'Get information about Nice Classification classes used for trademark registration.' It clearly states the two lookup modes: specific class numbers or keyword search. It does not explicitly differentiate from siblings like recommend_nice_classes, but the direct lookup framing is clear enough.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool—when you need class information by number or keyword—but it gives no explicit guidance on when to prefer this over alternatives such as recommend_nice_classes or search_goods_services. There are no exclusions or when-not-to-use notes.

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 destructiveHint, so the safety profile is covered. The description adds value by disclosing that 'Results are cached for 30 days' – a concrete behavioral trait not present in annotations. It also outlines the analytical scope, giving the agent expectations about the output's content. No behavioral contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler. The first sentence states the core purpose; the second lists covered content and caching behavior. It is front-loaded and every word 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?

Given the simple single-parameter API, annotations that cover safety/idempotency, and the descriptive scope of the summary, the description is largely complete. It includes the prerequisite to search_by_owner and the caching detail. The lack of an output schema means return format isn't specified, but for a summary-generation tool, the content description is sufficient 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 100%, so the baseline is 3. The main description does not add any parameter-specific meaning beyond what the schema already provides. The schema's parameter description is helpful (covers format and instructs to use search_by_owner), but the description itself contributes no additional semantic enrichment.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb-resource pair: 'Get an AI-generated strategic analysis of a trademark owner.' It explicitly distinguishes from sibling tools like get_mark_ai_summary by owner scope, and the listed content areas (brand protection philosophy, litigation posture, portfolio evolution, class distribution, future behavior) make the purpose unmistakable. This is far beyond a tautology.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when to use the tool: when an AI-driven strategic owner analysis is needed. The parameter description adds a strong prerequisite: 'Use search_by_owner first to find the correct normalized name.' It doesn't explicitly mention when not to use it or alternatives, but the context is unambiguous enough for an agent to select it correctly.

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 signal read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond that: it only uses public USPTO owner resolution, only returns system-generated deadlines, and explicitly excludes workspace/client/reminder/user-created deadlines. This helps an agent understand data provenance and limitations without contradicting 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?

The description is two sentences with no filler. The first sentence front-loads the core operation and scope; the second states the privacy/data-source limitations. Both sentences earn their place and the description remains highly scanable.

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 description, combined with the annotations, output schema, and 100% schema coverage, gives an agent everything needed to select and call the tool correctly. It clarifies data scope, exclusions, and the owner-level perspective without needing to repeat parameter or return-value details already present in structured fields.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all seven parameters are already documented in the schema. The description does not add parameter-specific detail, though the owner-scoping language reinforces the meaning of owner_name. This meets the baseline for a fully schema-documented tool.

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 public, system-generated trademark deadlines for a specific owner's marks. The owner-level scope clearly differentiates it from firm- and mark-level siblings like get_firm_deadlines and get_mark_deadlines. It also explicitly disclaims workspace, client, reminder, and user-created data, making its scope 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?

Provides clear selection context by emphasizing public USPTO owner resolution and system-generated data, and explicitly says it does not expose workspace, client, reminder, or user-created deadline data. However, it does not name sibling alternatives outright or state explicit 'use this instead when...' guidance, leaving some inference to the agent.

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, destructiveHint=false, and idempotentHint=true, so the safety profile is known. The description adds the output detail (breakdown by Nice class) but does not disclose behavioral traits like pagination, data freshness, or rate limits. With annotations covering the core behavior, 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?

Two sentences with no filler. The core purpose and output are front-loaded, and every word contributes. This is an exemplar of concise, structured documentation.

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 convey what the tool returns; it does so by stating 'yearly filing counts broken down by Nice class' and 'shows how the owner's trademark portfolio has evolved.' This is sufficient for an agent to know the expected result, though the exact structure (e.g., list vs. object) is not specified. Given the simple parameter set and read-only nature, this is near-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 100% – all three parameters (owner_name, start_year, end_year) are already documented in the schema. The description does not add any parameter-specific meaning beyond what the schema provides, so the baseline of 3 applies.

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 action (get) on a specific resource (trademark owner's filing trends) and provides detailed scope: yearly filing counts broken down by Nice class, plus the purpose (showing portfolio evolution). This clearly distinguishes it from sibling tools like count_filings_by_period or get_owner_ai_summary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is used when you need filing trends over time, but it does not explicitly state when to prefer this over alternatives such as count_filings_by_period or get_top_filers. The parameter description for owner_name mentions using search_by_owner first, which is a prerequisite but not tool-selection 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, and destructiveHint=false, so the safety profile is covered. The description adds a behavioral detail about what it shows (products/services focus), which is useful but not extensive. No contradiction with 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 sentences, no fluff, action verb front-loaded. Every word contributes to purpose or value. Perfectly concise.

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 tool with 2 parameters and no output schema, the description explains the purpose and expected result (most frequent keywords). It could mention the output format or any pagination, but given the simplicity, it is largely 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 100% for both parameters (limit and owner_name), so the baseline is 3. The description does not add extra semantic detail beyond the schema; it only reiterates that the tool surfaces focus areas, which is not parameter-specific.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'most frequent goods/services keywords for a trademark owner', which is specific and not a tautology. It does not explicitly name sibling tools to differentiate, but the resource is distinct enough among the many search and analytics 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 a high-level purpose ('useful for understanding their brand strategy') but no explicit guidance on when to use this tool versus alternatives. The schema includes a note to use search_by_owner first, but the main description itself provides no usage context or 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 readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context by disclosing that results include evidence and a high/possible confidence tier, with 'possible' marked as tentative. It also specifies that agent addresses are excluded from evidence, which is useful nuance beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is relatively long but every sentence contributes value: core purpose, evidence types, return details, usage guidance, and name-resolution note. It is front-loaded with the primary action and tapers into practical details. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there is no output schema, the description adequately covers the return shape (evidence and confidence tier) and the caution about 'possible'. It also covers input requirements and typical use cases. Minor gaps include pagination or limit behavior, but the limit parameter is self-explanatory and the tool is read-only, so the description is sufficient for an agent to invoke 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?

Both parameters have schema descriptions (100% coverage), so baseline is 3. The description adds extra guidance on owner_name: pass it exactly as recorded and resolve first if ambiguous. It also notes internal normalization to the owner key, which helps the agent understand the parameter's semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's verb ('Find') and resource ('entities likely related to a trademark owner'), and specifies the types of relationships (predecessors, subsidiaries, sister companies) and evidence sources. This distinguishes it from sibling tools like get_owner_ai_summary or get_chain_of_title without explicitly naming 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 description gives explicit use cases: analyzing an owner's full corporate family, portfolio scope, or determining affiliation between owners of similar marks. It also advises resolving the owner name with resolve_trademark_subject first if ambiguous. It doesn't explicitly name alternative tools or exclusions, but the context is clear enough for an agent to decide when to use 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, and destructiveHint, so the description correctly aligns with a read-only analysis tool. It goes further by disclosing an important data limitation: claimed-color metadata identifies candidates but does not prove color was alleged in the pleading, and it explains that qualifying filters apply only to target marks while all attached targets are reported separately.

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?

Four sentences cover purpose, core filtering behavior, an edge-case usage, and a critical caveat with no wasted words. The most important identity statement is front-loaded, and each subsequent sentence adds distinct information rather than restating 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?

For a tool with 13 parameters, this description covers the essential analytical behavior, a key invocation pattern, and the most likely misinterpretation. The lack of an output schema means some return-shape ambiguity remains, but the description's focus on counts and separately reported targets mitigates that 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?

With 77% schema coverage, the schema handles most parameter meaning, but the description adds value beyond it: target_class_match=only is tied to exact class-only questions, and the claimed-color fields are clarified as metadata-based rather than proof of pleading allegations. This helps an agent interpret the color and class parameters correctly without repeating the full schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Analyze one trademark owner's TTAB enforcement in a single call.' It then clarifies the tool's distinct filtering-and-counting behavior and explicitly names analyze_ttab_proceeding as the sibling to use when color allegations must be proven, distinguishing this tool from an obvious alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for the tool's analytical role and explicitly routes color-evidence questions to analyze_ttab_proceeding. It also calls out the exact-class-only use case via target_class_match=only, but it does not contrast this tool with get_owner_ttab_stats or other enforcement-related siblings, so the guidance is useful but not exhaustive.

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/destructive safety, so the burden is low, but the description adds a critical caveat: the total counts every record including extensions and defended cases, not just oppositions the owner started. This prevents a common misinterpretation.

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 sentences with no filler: the first states the result, the second clarifies the counting semantics, and the third routes to the sibling. Information is front-loaded 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?

For a simple 3-parameter stats tool with full safety annotations, the description explains what the counts include and exclude and where to go for more detail. It does not describe the exact return shape, but the count categories are specified, so no critical usage information 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 covers owner_name and year; description reinforces 'one owner' but offers no additional meaning for the limit parameter. With 67% coverage, the description provides modest value but does not fully compensate for the undocumented 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?

Description opens with a specific verb and resource ('Returns a compact TTAB history for one owner') and enumerates the exact count categories, making it clear what the tool produces. It also names the sibling get_owner_ttab_enforcement, which helps distinguish scope.

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 explicitly contrasts this tool with get_owner_ttab_enforcement, noting that the sibling covers date ranges and the marks and classes challenged. This tells an agent when to prefer the sibling without ambiguity.

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 behavior. The description adds valuable behavioral context on top: the list-returning fallback when no selector is supplied, the returned fields (link, extraction status, cached text, excerpts), and the document-list shortcut. It is transparent without contradicting 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?

Three focused sentences with no filler. The core retrieval behavior is front-loaded, followed by the return summary and practical usage tips. 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?

Given no output schema and seven parameters, the description covers the essential invocation paths, return content, and fallback behavior well. It does not explicitly explain max_chars' effect on returned text, which is the one parameter without a schema description, but the overall guidance is sufficiently complete for correct use.

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 high at 86%, so the baseline is 3. The description adds meaning beyond the schema by explaining that document_id is stable and returned from list_prosecution_documents, that text_query yields query-centered excerpts, and that serial_number alone returns the document list. This meaningfully supplements the parameter documentation.

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 uses a specific verb-resource pair: 'Retrieve one specific USPTO prosecution document', and clearly distinguishes this single-document retrieval tool from list_prosecution_documents. It also names the key selectors, making the tool's identity immediately clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit usage guidance: use text_query when the user asks what a document says about an issue, and call with serial_number alone to get the document list without a separate list_prosecution_documents call. This effectively tells the agent when and how to invoke this tool versus its closest sibling.

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 destructiveHint, covering safety. The description adds that the output is chronological and raw, but does not disclose any pagination, filtering, or error behavior. Given the annotations cover the safety profile, the description provides moderate additional context but not rich behavioral detail.

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 concise sentences, front-loaded with the primary purpose and immediately followed by a clarifying list of contents. There is zero waste, and the 'Raw data without AI analysis' note is succinct and valuable for sibling differentiation.

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 getter with one parameter, no output schema, and annotations covering safety, the description provides sufficient context: what the tool returns (chronological list of events) and its nature (raw data). It does not mention response format or error handling, but these are minor given the tool's 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 coverage is 100% for the single parameter serial_number, which is described as 'USPTO serial number.' The description does not add any additional meaning beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool gets a prosecution timeline for a trademark, listing specific event types (office actions, responses, publication, registration, suspension). It distinguishes itself from analysis tools by explicitly saying 'Raw data without AI analysis,' which sets it apart from siblings like analyze_prosecution_history. The verb-resource pairing is precise.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use it (when raw chronological data is needed) and implicitly contrasts with AI analysis tools. However, it does not explicitly name an alternative tool or state a condition like 'use analyze_prosecution_history for analysis.' The guidance is clear but not fully explicit about 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's safe. The description adds context about the scope (USPTO/TTAB codes and small tables) but doesn't elaborate on return format, pagination behavior beyond the schemas, or any limitations. It does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is concise and information-dense. It front-loads the purpose (look up reference codes) and then lists example categories. No filler words. It earns a high score for being efficiently structured, though it could be slightly more explicit about usage exclusions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that the tool has 5 parameters with full schema coverage, no output schema, and no nested objects, the description covers the core purpose. It lacks details on which specific reference types are included (though the enum covers that) and doesn't mention edge cases like when to use code vs query. However, for a lookup tool, the schema plus annotations suffice for an agent to call it correctly. Minor gaps: no mention of return format or error cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, meaning all five parameters are documented in the schema. The description mentions 'look up codes and small lookup tables' which aligns with the reference_type enum, but it doesn't add meaningful semantic detail beyond the schema. For example, it doesn't explain the relationship between code and query, or the after_code pagination cursor. Baseline 3 is appropriate since schema covers semantics fully.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool's purpose: looking up USPTO or TTAB reference codes and small lookup tables. It uses a specific verb ('look up') and lists the resource categories (status codes, statement types, legal entity types, Nice classes, design codes, TTAB codes). It distinguishes itself from siblings like get_nice_classes and get_event_code_reference by covering broader reference tables, though it doesn't explicitly 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 description implies when to use: when needing to look up reference codes or enum-like values. However, it does not explicitly mention when to use alternatives like get_nice_classes or get_event_code_reference, nor does it state when not to use this tool. The context suggests it's for small lookup tables, but the distinction from similar tools is not explicit.

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 destructiveHint, so the safety profile is covered. The description adds useful behavioral context by explaining the examiner-style matching approach and the semantic difference between similarity_score and confusion_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?

The description is three sentences with no filler. It front-loads the core purpose, then efficiently adds matching method, output semantics, and the intended use case—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?

Given the output schema, complete parameter descriptions, and safety annotations, the description covers what an agent needs to invoke the tool. The only minor gap is not explicitly routing to or distinguishing from very similar sibling tools such as run_knockout_search and compare_marks.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters are already documented. The description reinforces mark_text as the core input and clarifies the meaning of the score outputs, but it does not add meaning beyond the schema for limit, include_dead, or nice_classes.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Find'), the resource ('USPTO trademarks'), and the input ('a given mark name'). It further distinguishes the tool by explaining the matching method (phonetic, trigram, component) and the scored outputs (similarity_score, confusion_score), making it identifiable among 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 description explicitly names a use case: trademark clearance searches. It does not state exclusions or directly compare with alternative sibling tools like run_knockout_search or compare_marks, but the intended context is clear enough for an agent to select 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 readOnly/idempotent/non-destructive, but the description adds substantial behavioral detail: it returns per-filer live/registered/pending counts plus corpus totals, explains limit/offset for rank bands, describes success_rate and the min_filings floor to prevent skewed rankings, and clarifies filer_profile semantics including the curated filing-service list and how to exclude them. This goes well 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?

Three sentences that front-load the core purpose, then give a usage example, then explain pagination. Each sentence earns its place with zero filler or repetition.

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 9 parameters, existing annotations, and an output schema, the description is remarkably complete: it covers date ranges, filer types, Nice classes, pagination, ranking options, and behavioral caveats. The output schema handles return structure, so the description doesn't need to; the only gap is explicit sibling differentiation, which belongs more to usage guidelines.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description enriches limit/offset with a concrete example (ranks 40-45 = limit 6, offset 39) and clarifies that a single call covers the full ranked list. Most parameter-specific nuances (e.g., filer_profile meanings) are already in the schema, so the description supplements rather than compensates.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb+resource ('Get a ranked filer table') and specifies the scope (date range, filer type, Nice classes). It distinguishes itself from siblings like get_ttab_top_opposition_filers or get_firm_top_correspondents by being a general top-filers ranking tool, so an agent can immediately tell what it does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a concrete example ('Who are the top 10 filers in Class 9 in 2025?') and implies when to use it for ranked-filer questions. However, it never explicitly contrasts with sibling tools or states when not to use it, leaving the agent to infer the boundary against specialized 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 the tool read-only, idempotent, and non-destructive. The description adds valuable output expectations beyond those annotations: filing metadata, viewer link, conditional 'direct PDF link when available', extraction/readability status, document text, and optional excerpts. This gives the agent a reliable picture of what a successful call returns.

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 three tight sentences: the action, the return payload, and the usage condition. Every sentence earns its place, and the most decision-relevant information is front-loaded.

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 single-document retrieval with no output schema, the description covers the key context: what identifiers are needed, what the response contains, and how to discover the entry number. A minor gap is that max_chars truncation behavior is not explained, which could affect interpretation of 'document 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 descriptions cover 3 of 4 parameters (proceeding_number, entry_number, text_query) with useful format and source context. The description reinforces these by mentioning 'proceeding number and entry number' and 'query-centered excerpts', but it adds no new meaning for max_chars, which remains undocumented in both the schema and the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific action, 'Retrieve and read one specific TTABVUE filing', and identifies both required identifiers, proceeding number and entry number. This clearly distinguishes it from sibling tools like get_ttab_proceeding_details, which handles broader proceeding-level data.

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 explicitly instructs agents to 'Use get_ttab_proceeding_details first when the entry number is unknown', directly addressing the main alternative and the condition for choosing it. The schema also reinforces that entry_number comes from get_ttab_proceeding_details, creating a clear workflow.

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 destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context by specifying the nature of the data ('raw details') and including 'working TTABVUE document links,' which implies functional links. This adds value beyond the annotations without contradicting them.

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 concise sentences, with the primary purpose front-loaded and the routing guidance as a clear secondary sentence. There is no fluff, and every clause 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 read-only, single-parameter tool with no output schema, the description fully covers what the tool returns, how to use it, and when to use alternatives. No essential information 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 100%, so the single parameter (proceeding_number) is fully documented in the schema with an example. The description does not add any additional nuance or format details beyond what the schema provides, so the baseline of 3 applies.

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 uses a specific verb ('Get') and resource ('raw details for a TTAB proceeding') and enumerates the included data types (parties, marks, counsel, recent filings with entry numbers and links). It clearly differentiates from siblings like get_ttab_document, get_owner_ttab_enforcement, and analyze_ttab_proceeding by naming them 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 description provides explicit when-to-use and when-not-to-use guidance: 'Use get_ttab_document to read one selected filing' and 'Use get_owner_ttab_enforcement for owner-wide distributions and analyze_ttab_proceeding for AI-powered merits analysis.' This leaves no ambiguity about tool selection.

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 agent knows this is a safe, non-mutating operation. The description adds the scoping constraint (market-wide, date-range) but does not disclose return format, pagination, or behavior on empty results. With annotations covering safety, 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?

Three sentences with no redundancy. The core purpose is front-loaded, and the alternative-tool mention is placed at the end. Every sentence earns its place; no fluff.

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 description is complete for an agent to decide when to call it and what it does. It lacks explicit return format, but since there is no output schema and the tool is a ranking, the expected output is implied. The mention of alternatives covers routing. Given the complexity (5 params, but schema covers them), this is adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter has a detailed explanation (e.g., party_role explains plaintiff vs defendant, date formats are given). The description adds minimal additional parameter meaning beyond restating the date-range and ranking intent. Baseline 3 is correct when the schema already does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Ranks' and the resource 'TTAB oppositions (or cancellations)' across the whole Board. It explicitly names two sibling tools (get_owner_ttab_stats, get_ttab_proceeding_details) to distinguish its scope, leaving no ambiguity about what this tool does.

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 provides clear context: answers market-wide ranking questions over a date range, and explicitly mentions alternatives for owner-specific and proceeding-specific data. However, it does not explicitly state when NOT to use this tool (e.g., if a single owner's stats are needed), though the alternatives imply that. Slight gap in explicit 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 indicate this is read-only, idempotent, and non-destructive; the description adds substantial behavioral context by explaining the market-specific fame test, the class-as-market proxy, and the legal caveat that fame is not universal. It also discloses important output semantics such as is_famous, famous_in_class, fame tier, portfolio size, and TTAB plaintiff history.

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 front-loaded with the core action and then systematically covers return fields, legal relevance, and an important caveat. The legal citation is dense but earns its place by preventing the common assumption that fame is class-agnostic. There is no 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 compensates by listing the major return signals and framing their legal significance. The optional class behavior is already covered in the schema, and the caveat addresses interpretation risk. An agent has enough information to select and invoke this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents both parameters. The description adds value by framing the class parameter as a proxy for the relevant market and explaining why fame is market-specific, which helps the agent decide when to supply or omit the class. It does not add much beyond the schema for the mark 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 opens with a specific action ('Checks whether a trademark is famous') and a clear resource, then adds market-specific nuance and the main return values. It is distinguishable from sibling fame/profile tools by its focus on fame tier, class-specific fame, and portfolio/TTAB context, though it does not explicitly name a sibling alternative.

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 provides clear legal contexts for use: likelihood-of-confusion strength under Section 2(d), dilution eligibility under Section 43(c), and general fame assessment. It also warns that the result is 'a circumstantial signal, not proof of statutory fame,' but it does not name alternatives or state explicit when-not-to-use conditions.

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 destructiveHint, so the safety profile is covered. The description adds useful behavioral context beyond the schema by revealing what is returned: stable identifiers, working USPTO links, readability/extraction status, and document categories.

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 tightly written sentences convey purpose, output contents, and the relevant sibling alternative. The main action is front-loaded and every phrase 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?

Despite lacking an output schema, the description sufficiently characterizes the return contents and invocation context for a list operation. It also routes the agent to the correct follow-up tool, making it complete for selecting and invoking the 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?

Schema description coverage is 100%, so both serial_number and limit are already documented. The description restates serial_number as the key input but adds no new semantic detail about the limit parameter or how parameters affect results.

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 ('List') and resource ('prosecution documents for a trademark serial number'), and enumerates exactly what is included. It also distinguishes itself from the sibling get_prosecution_document by directing the agent there for reading a single selected document.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a clear context for use (list documents for a serial number) and an explicit alternative for the next step ('Use get_prosecution_document to read one selected document'). It does not compare with other prosecution-history siblings like get_prosecution_timeline or get_latest_office_action, so it lacks full exclusionary 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, and destructiveHint=false, covering the safety profile. The description adds the list of return fields and the correspondent usage note, which provides useful behavioral context beyond the annotations. It does not contradict any annotation, and the added information is relevant for the agent's decision-making.

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 a single sentence that front-loads the core purpose ('Get detailed information about a specific USPTO trademark by its serial number') and then lists key fields. It is efficient, though the list of fields makes it slightly longer than necessary. No wasted words; the correspondent note is purposeful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema, the description does not need to explain return values. It is a simple one-parameter lookup, and the description covers the main purpose, typical fields, and a specific usage hint. The only minor gap is not explicitly stating when not to use it, but the context and annotations are sufficient for an agent to use 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?

The input schema has 100% coverage for the single parameter serial_number, with a description 'USPTO serial number (exactly 8 digits)' that is clear. The tool description only says 'by its serial number,' which adds no new meaning beyond the schema. Per the baseline, with high schema coverage, a score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb ('Get'), a specific resource ('detailed information about a specific USPTO trademark'), and the key identifier ('by its serial number'). It also enumerates the fields returned (owner, status, filing dates, etc.), making it unambiguous what the tool does. It differentiates from siblings that target narrower aspects (e.g., get_correspondent_marks) by virtue of being the general serial-number-based lookup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives an explicit usage hint: 'use this for "which firm represents/is correspondent for" questions,' which helps route the agent. It does not explicitly contrast with alternatives, but the serial-number-by-lookup nature makes the primary use case obvious. The note about correspondent questions is a clear when-to-use pointer, though it could have named a sibling like get_correspondent_marks as an alternative for that specific need.

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. The description adds valuable behavioral context beyond that: the whole-mark threshold behavior, the non-exhaustive nature of empty results, and the explicit disclaim that it is not a clearance search. These are meaningful additions that help the agent interpret results correctly.

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 dense but efficient. It front-loads the core purpose, then adds a critical limitation with an example, and closes with a direct routing to the correct alternative. Every sentence earns its place; no fluff or redundancy.

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 an output schema present, return format is covered. The description fully explains the search's scope, limitations, and interpretation of results, and provides an alternative. It does not detail each parameter (already partially in schema) but the behavioral guidance is strong. Given the tool's complexity and the sibling landscape, it is near-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 only 40% (mark_text and nice_classes have descriptions). The description does not explain the other three parameters: limit, include_dead, and similarity_threshold. It mentions 'whole-mark threshold' conceptually but does not connect it to the similarity_threshold parameter or explain its range/default. The description does not compensate for the low schema coverage.

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 ('Finds'), resource ('trademarks'), and the method (Metaphone codes + trigram similarity) with a precise scope (whole-mark comparison). It clearly distinguishes from siblings like get_similar_marks (broader similarity) and run_knockout_search (conflict search) by explaining what it does and does not do.

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?

Explicitly provides when-to-use and when-not-to-use: the whole-mark limitation is illustrated with a concrete example (QUICK vs KWIK REWARDS), and the description explicitly says an empty result is not a clearance result and names the alternative (run_knockout_search) as the conflict search. This is exemplary 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 cover the read-only, idempotent, non-destructive profile, so the description's main job is to add behavioral context. It does this by disclosing the return type: most relevant classes with confidence scores and explanations. This goes beyond the annotations and gives the agent a useful expectation of the output.

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, front-loaded sentences with no filler. The first sentence states the core function, and the second discloses the output format. Every word 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 read-only recommendation tool with a simple two-parameter schema, the description is largely complete: it states the input basis, the output shape, and the relevance framing. It could be slightly richer about the exact format of the returned classes, but the annotations and schema cover most operational needs.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description doesn't add much parameter meaning beyond the schema; it implicitly reinforces that business_description is the core input but doesn't explain industry usage or output structure beyond what is already stated.

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 uses a specific verb ('Recommend') and resource ('Nice trademark classes'), and clarifies the basis ('business description'). It also differentiates from sibling tools like get_nice_classes by noting it returns ranked, relevant classes with confidence scores and explanations.

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 clearly signals when to use this tool: when the user provides a business description and needs class recommendations. It doesn't explicitly state when not to use it or name alternatives, but the context is clear enough for an agent to select it over lookup-style tools like get_nice_classes.

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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true), the description adds material execution context: it launches asynchronously for authenticated users, typically takes 1-2 minutes, and returns a processing handle. This is genuinely useful behavioral disclosure not present in 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?

The description is two sentences with no filler. The first sentence front-loads the core purpose and outputs; the second adds essential async behavior. 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?

For a one-parameter tool, the description covers purpose, return content categories, and execution model well. The only minor gap is that it does not explain how the returned processing handle should be consumed to retrieve the final result, but this does not prevent a correct initial call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single parameter serial_number is fully described in the schema. The description does not add further parameter-level semantics, so the baseline of 3 applies.

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 action ('Research the Office Action') and a concrete resource (a trademark), then enumerates the return categories: refusal categories, OA/response context, cited marks, and third-party registrations. This clearly differentiates it from siblings like get_latest_office_action, which implies a simpler retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for deep Office Action analysis and notes that authenticated users get asynchronous execution, but it does not explicitly name alternatives or state when to choose this over get_latest_office_action or analyze_prosecution_history. The agent must infer routing from the listed outputs.

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, non-destructive behavior. The description adds valuable context beyond annotations: the return behavior (exact match vs. candidates) and the authentication requirement for clients/portfolios. It does not mention rate limits or detailed output format, but the added context is meaningful.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler, and the core function is stated up front. The additional auth note is placed at the end, keeping the structure clean.

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 tool with moderate complexity, the description covers the purpose, ambiguity handling, and a key auth constraint. It lacks an explicit statement about return format or ordering of candidates, but the absence of an output schema and the presence of annotations make this acceptable. Overall, it is sufficiently complete for an agent to use 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 100%, so the baseline is 3. The description does not add significant per-parameter meaning beyond the schema; it lists entity types (already in the enum) and mentions ambiguity/candidates, but this is behavioral rather than parameter-specific. It doesn't explain 'limit' or add format details for subject_name.

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 ('Matches') and a specific resource ('trademark entity'), enumerating all entity types, and distinguishes its behavior (exact match vs. top candidates) from broader search/lookup siblings. It is not a tautology and clearly tells an agent what this tool does.

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 provides clear usage context: it resolves an ambiguous name and returns a match or candidates. It also gives a prerequisite (signed-in account for clients/portfolios). However, it does not explicitly name alternative sibling tools or state when NOT to use this tool, so it falls 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?

The description goes well beyond the readOnly/idempotent annotations by disclosing result tiers, headline verdict structure, dead-mark sampling, performance expectations, and a signed-in account requirement. It even includes measured timing for include_dead (150s then failed), which is highly useful for agent timeout decisions. There is no contradiction with 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?

The description is dense but every sentence earns its place: engine capabilities, output structure, parameter caveats, exclusions, timing, and authentication are all covered without filler. Key constraints are front-loaded, and the performance data is placed near the include_dead warning where it matters most.

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 by explaining exactly what the agent will receive: four risk tiers, a four-level verdict with a one-line reason, and a dead-mark sample. It also covers practical call context such as runtime, authentication, and parameter tradeoffs, making the tool fully callable by an agent without further inference.

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?

Although the schema descriptions already cover 100% of parameters, the tool description adds crucial meaning: goods_description is tied to relatedness scoring with a concrete understatement risk, owner_name is explained as adding portfolio context, and include_dead gets behavioral warnings beyond schema defaults. This substantially enriches parameter understanding for correct invocation.

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 leads with a specific verb and resource: 'Runs a scored trademark conflict (knockout) search over 14M USPTO records.' It names the matching engine and result structure, making the tool's identity unmistakable. It also distinguishes itself from domain coverage by pointing to check_brand_availability, so agents can tell it apart from sibling 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?

Usage guidance is explicit: it states when to set include_dead (only if the user explicitly asks about dead/abandoned marks) and when not to ('LEAVE IT FALSE for availability / what would block me questions'). It also names check_brand_availability as the alternative for domain/web checks and highlights when goods_description is strongly recommended. This gives the agent clear decision rules rather than leaving usage to inference.

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