GleanMark Trademark Search

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

Annotations declare readOnlyHint=true and destructiveHint=false, so the tool is a safe read operation. The description adds critical behavioral context: the async launch for authenticated users, what kind of result (a processing handle) and the expected completion time. This goes beyond annotations and is essential for correct 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 with precise information, no fluff. The core purpose is front-loaded, then the async behavior is stated clearly. 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 tool has one parameter, high schema coverage, and clear behavioral disclosure, the description is sufficiently complete. It lacks a return format description, but since there's no output schema and the async handle is mentioned, an agent can infer. The tool's simplicity means no additional context is needed.

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 covers 100% of the single parameter with 'USPTO serial number'. The description does not add detail beyond that, but since coverage is high)Skip the baseline is 3. The description does not introduce any ambiguity; it appropriately leaves parameter details to the schema. However, it could add context on formatting (e.g., 8-digit number) but that's marginal.

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 explicitly states the tool analyzes the full prosecution history of a trademark, providing a narrative timeline and examiner-behavior patterns. It distinguishes this from siblings like get_prosecution_timeline or get_mark_prosecution_summary by emphasizing the narrative and pattern aspects. The verb 'analyze' and resource 'prosecution history' are specific and 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 explains the asynchronous nature for authenticated usersainer, which is a key usage guideline. It differentiates from siblings by focusing on the full narrative history with examiner patterns, whereas siblings like get_latest_office_action or list_prosecution_documents are more specific or discrete. The context of 'usually done in under a minute' guides agents on expected latency.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond that: it discloses the asynchronous execution (1-2 minutes), that it returns a processing handle, and that quick_mode affects document coverage. These details are not in annotations and materially help the agent set expectations.

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

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

Two sentences with no filler. The first sentence front-loads the purpose and expected output, the second conveys the critical async caveat. Every word earns its place, and the structure makes the most important information immediately visible.

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

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

For a complex analysis tool with no output schema, the description covers the key deliverable (structured summary with timeline, positions, assessment) and the async flow. It mentions authentication requirements and quick_mode. It doesn't detail how to use the processing handle to retrieve results, but that is likely explained elsewhere or in the output documentation. Given the complexity, it's nearly complete, missing only a minor retrieval instruction.

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 parameters (proceeding_number and quick_mode) are fully documented in the schema. The description adds minimal extra meaning: it implies that quick_mode trades depth for speed and that the handle is for retrieval, but these are already implied by the schema. Since the schema carries the heavy lifting, a 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 ('Analyze'), a precise resource ('TTAB proceeding'), and the outcome ('returns a structured summary with timeline, party positions, and strategic assessment'). It clearly distinguishes from sibling tools like get_ttab_proceeding_details (which likely only fetches details) and search_ttab_proceedings (which searches), making the purpose 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 gives clear context for when to use the tool: for deep analysis versus simple retrieval. It also mentions the asynchronous behavior for authenticated full-mode runs, which is a critical usage note. However, it doesn't explicitly exclude alternatives or state 'use this instead of X', though the name and phrasing imply it. The guidance is solid 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?

Beyond the readOnly/openWorld/destructive annotations, the description discloses important behavioral limitations: it ignores common-law rights, state registrations, and goods relatedness depth. It also specifies the exact screening tier values and prescribes safe reporting language, which prevents the agent from making overclaiming statements.

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. It front-loads the core purpose with 'Quick brand SCREEN', then uses clear warnings and explicit reporting instructions. The structure makes the critical distinction between screening and clearance immediately visible.

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 legal nuance of trademark screening and the absence of an output schema, the description is remarkably complete. It explains what the tool does not see, what it returns, how to phrase results, and where definitive availability comes from. An agent has enough context to invoke it and interpret its output 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. The description adds some context by mentioning that the trademark conflict signal is 'for the industries given,' but it does not elaborate on nice_classes, business_description, or how these parameters interact. The schema descriptions are minimal, but the description does not need to compensate heavily because the parameters are self-explanatory.

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 as a quick brand screening service combining domain availability with a trademark conflict signal, and explicitly distinguishes it from an availability answer. It names the competitor sibling run_knockout_search, so an agent can select it correctly.

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: it is a quick screen, not a clearance search, and never an availability answer. It also directs final availability conclusions to run_knockout_search and instructs the agent to point users to a complete clearance search.

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

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

Annotations already convey read-only and non-destructive behavior. The description adds value by specifying the return statuses and .com variations, but doesn't disclose additional behavioral details like rate limits or data freshness.

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 clear, front-loaded sentences with no redundancy. Every word contributes meaning.

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 return statuses and .com variations, which is substantial. It could optionally mention that results are per-TLD, but the coverage is solid for a simple read-only 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 parameters are well-documented. The description adds context about .com variations corresponding to the brand_name parameter, but doesn't go beyond what the schema already explains for tlds.

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 it checks domain availability for a brand name and lists return statuses. It is distinct from most trademark tools due to domain focus, but does not explicitly differentiate from the sibling 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?

Usage is implied: it's for domain availability checks. However, no explicit guidance is given on when to use this tool versus alternatives like check_brand_availability or web_research, and no exclusion criteria are mentioned.

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 safe. The description adds methodology (DuPont-style analysis) and output type (similarity scores, risk assessment), which provides some behavioral context beyond the annotations. However, it does not disclose potential limitations, data sources, or scope nuances, so transparency is adequate but not rich.

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

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

The description is two sentences, front-loaded with the core purpose, and contains zero wasted words. Every sentence earns its place: the first states the function, the second summarizes the output.

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, annotations, and a clear two-sentence description, it is reasonably complete for a pairwise comparison tool. The description covers what it does and what it returns. It could benefit from clarifying the relationship to run_dupont_analysis or the jurisdictional scope, but these are not critical gaps given the existing structured metadata.

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 covers 100% of parameters with descriptions, so the baseline is 3. The description does not add meaningful semantic details beyond the schema; it simply reiterates that two marks are compared. The nice_classes parameter is already described as 'Nice classes for overlap analysis,' and the description adds no clarification about mark formats or analysis scope.

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 function: compare two trademarks for likelihood of confusion using DuPont-style analysis. It names the specific resource (two trademarks) and the analytical approach, which distinguishes it from siblings like get_similar_marks or phonetic_search. However, it does not explicitly differentiate from the closely related sibling run_dupont_analysis, which may perform a similar role, so not a full 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 usage when a user needs to compare two specific trademarks for confusion risk, but it does not explicitly state when to use this tool over alternatives such as run_dupont_analysis or get_similar_marks. No exclusions or alternative recommendations are provided, leaving the choice ambiguous among similar 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 and destructiveHint=false, and the description adds context beyond this: it mentions 'preview' behavior and 'metadata coverage,' and clarifies that it can intersect color criteria. This gives the agent a clearer sense of the tool's functional scope without contradicting 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 purpose and key differentiators; the second delivers usage scope and exclusions. Every phrase earns its place, making it compact and 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 9-parameter tool with no output schema, the description gives a good high-level orientation but omits important invocation details: whether limit affects counts or only previews, how class_match_mode behaves, and the exact return structure. It is sufficient for tool selection but not fully complete for a complex 9-param 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 44% (low), and the description compensates partially by mapping core concepts: 'mark-type' to mark_types, 'standard-character' to standard_characters, 'Nice-class' to nice_classes, 'status' to status_filter, and 'claimed-color criteria' to the color params. However, it does not explain limit, class_match_mode, or interaction nuances, leaving some parameters underspecified.

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: 'Count and preview USPTO marks by record attributes.' It distinguishes from sibling tools by emphasizing 'rather than owner identity' and explicitly excluding 'color-only counts, rankings, lists, and vocabulary,' which differentiates it from tools like search_by_owner or color-focused searches.

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 guidance: 'Use this for drawing type, standard-character, Nice-class, status, and cross-attribute counts.' It also gives exclusions ('color-only counts... are outside its scope'), helping the agent decide against this tool for those needs. However, it does not name specific alternative sibling tools, so it falls short of perfect alternative 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 indicate this is read-only and non-destructive. The description adds behavioral context by specifying the returned fields and the public gleanmark.com citation URL, which is especially valuable given the absence of an output schema. No contradiction with annotations exists.

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

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

The description is a single well-structured sentence that front-loads the core action and then enumerates the return contents. Every piece of information serves a purpose without redundancy or 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?

Given the simple one-parameter schema, read-only annotations, and no output schema, the description provides sufficient context: what the tool does, where the id comes from, and what the results include. Nothing essential for calling the tool correctly is missing.

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

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

The input schema already fully documents the single 'id' parameter with an example and accepted alternative format. The description adds meaning by explaining that the id comes from a search tool result and that the tool retrieves one trademark, which helps the agent correctly source and pass the parameter.

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

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

The description states a specific verb ('Retrieve') and resource ('the full USPTO record for one trademark'), and clarifies the required input is an id from the search tool. It also lists the key record fields returned, making the tool's function unmistakable and distinct from broad search tools.

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

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

The description clearly indicates this tool should be used after a search, using an id returned by the search tool. It does not explicitly state when not to use it or name alternative sibling tools, but the dependency on a prior search is a clear and useful usage signal.

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 mark the tool as read-only and non-destructive, and the description adds meaningful behavioral context beyond that: what data is included (recorded ownership stages and assignment documents), a joint-owner interpretation caveat, and a legal non-opinion disclaimer. This gives the agent important information about output semantics that annotations alone do not convey.

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 behavior, followed by specific use cases, a sibling distinction, a joint-owner clarification, and a disclaimer. Every sentence earns its place; 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?

The tool has one parameter, a read-only annotation set, and no output schema, so the description carries most of the burden. It explains what data is returned, what questions the tool answers, how to interpret the data, and what it does not provide. Nothing essential is missing for an agent deciding whether and how to call 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?

The schema covers 100% of parameter documentation, including the serial number format and the explicit rejection of registration numbers. The tool description does not add parameter-level detail beyond that, but it does not need to given the schema's completeness.

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 identifies a specific action (trace ownership) on a specific resource (trademark ownership history over time) and clearly distinguishes itself from lookup_trademark, which only returns the current owner. The wording 'original applicant/registrant through each successive new owner' precisely defines 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 gives explicit when-to-use guidance: ownership changes, assignments, transfers, chain-of-title, and due-diligence questions. It also names the alternative lookup_trademark and explains why that tool cannot answer these questions, plus includes a clear exclusion ('Not a title opinion').

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 safety profile is known. The description adds useful behavioral context by explicitly mentioning two distinct result types (coordinated vs related), which maps to the relationship_type parameter and is not apparent from annotations alone.

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

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

The description is a single, front-loaded sentence with no superfluous words. Every word contributes to the core meaning.

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 lookup tool with well-described schema parameters, the one-sentence description is adequate. However, it could benefit from a brief note clarifying the difference between 'coordinated' and 'related' to prevent ambiguity, though the parameter description for relationship_type partially compensates.

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% with descriptions for all four parameters, so the baseline of 3 applies. The description adds no parameter-specific detail beyond what the schema already provides.

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

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

The description uses a specific verb ('look up') with a clear resource ('coordinated Nice classes or related Nice classes') and scope ('for a given class number'). It distinguishes itself from sibling tools like get_nice_classes (which likely lists all classes) and recommend_nice_classes (which recommends classes).

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 no guidance on when to use this tool versus alternatives such as get_nice_classes or recommend_nice_classes. It only states the function, not the 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 mark this as a safe read-only operation, and the description adds substantial behavior: it returns averages/medians/percentiles, counts marks lacking the start event, and discloses sampling behavior ('Samples up to max_sample marks from the start of the window and says so when truncated'). It also explains the max 366-day date window.

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 main action, uses a concrete example, and every sentence adds detail about parameters, return value, or usage. It is compact yet thorough, with 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?

For a complex analytics tool with no output schema, the description adequately specifies return values (avg/median/percentiles, missing-start counts, example marks), explains the sampling behavior, and gives a full workflow. It also cross-references a sibling tool for code lookup, making the tool self-contained.

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 already covers all 9 parameters with descriptions (100% coverage). The description adds semantic context by explaining how the cohort anchor, interval start/end, and raw event codes work together, and it defines the prefix wildcard ('trailing *') behavior, which is only partially present in 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 opens with a specific verb 'Aggregate' and identifies the resource 'event-to-event pendency across a COHORT of marks', followed by a concrete example. It distinguishes itself from sibling individual-mark tools by emphasizing the cohort scope and by referencing get_event_code_reference for event codes.

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 provides a clear use scenario with an example and instructs users to 'Pick the cohort by an anchor event... within a date window... and an interval start/end event.' It also explicitly directs to 'Use get_event_code_reference first' for non-preset codes, offering an alternative workflow. However, it does not explicitly state when not to use the tool (e.g., for single-mark queries).

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 safety profile is covered. The description adds behavioral context by stating the sort order ('sorted by prosecution history length') and the inclusion of event counts and office action flags, going 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, front-loaded with the core purpose, followed by return characteristics and usage guidance. Every sentence earns its place with no redundancy or 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?

The description effectively conveys the tool's scope and output characteristics, including sort order and included data types. It does not detail return fields or parameter selection logic, but the schema covers parameter semantics, and the annotations handle safety, making this sufficient for the tool's 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%, with all seven parameters having descriptions. The description does not add significant meaning beyond the schema, but it does reinforce that search_term/correspondent_name relate to attorney identity, matching the tool's purpose.

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 retrieves all trademarks handled by a specific attorney/correspondent, including prosecution event counts and office action flags. The phrase 'attorney-specific mark queries' distinguishes it from general trademark search tools like search_trademarks.

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,' providing a clear when-to-use context. It does not mention alternatives or when not to use the tool, but the use case is specific 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 and destructiveHint=false, so the safe read-only nature is covered. The description adds useful behavioral context about the output (top clients, Nice classes, prosecution/TTAB profile) but does not disclose potential resolution behaviors or edge cases. It contributes some value beyond 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?

The description is a single sentence that front-loads the main action and then adds usage guidance. No wasted words; every clause earns its place. It is highly concise while remaining informative.

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?

This is a read-only summarization tool with a rich output schema and full parameter documentation. The description explains the tool's purpose, when to use it, and key output elements, which is sufficient for an agent to select and invoke it. It does not describe return format, but the output schema compensates for that.

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%, with all five parameters described. The description does not add extra meaning beyond the schema, so the baseline score of 3 applies. It does not explain how parameters interact (e.g., url_key vs search_term priority), but the schema descriptions already cover each parameter individually.

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 summarizes what a named correspondent specializes in, with specific output components (top clients, Nice classes, prosecution vs. TTAB profile). This distinct 'specialization' focus differentiates it from sibling tools like get_correspondent_marks or get_firm_top_correspondents.

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 to use this tool when the user asks what a specific correspondent or attorney specializes in. It provides clear contextual guidance, though it does not mention alternatives or exclusion cases, so it earns 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 cover the operational safety profile with readOnlyHint=true and destructiveHint=false, so the description only needs to add behavioral context. It adds useful detail about the role vocabulary and the reference table, but it does not disclose return shape, behavior when no mapping exists, or any pagination/lookup properties. That is acceptable but not rich by the standard set by strong examples.

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 with the action front-loaded and no redundant words. The list of deadline types at the end is information-dense, which slightly hurts readability but is justified because it previews the enum space.

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

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

For a two-parameter, read-only lookup with no output schema, the description covers the core semantics well: what input items are, what the tool will compute, and what vocabulary the answer uses. It could be strengthened with a note about edge cases like missing mappings, but nothing is critically absent for 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 parameters are already individually documented. The description adds meaning beyond the schema by stating the domain table (deadline_event_roles) and listing the role categories and deadline families, which helps an agent know what response to expect and how the two parameters interact.

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 identifies a specific verb—'Check what role'—and a clear resource: the deadline_event_roles vocabulary table mapping event codes to deadline role. It also lists the possible role outputs, which makes the tool's purpose very concrete. It stops short of a 5 because it does not explicitly differentiate itself from sibling lookup tools like get_event_code_reference or get_event_status_mapping.

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 the many sibling reference tools. The description implies the intended use case, but no alternatives, exclusions, or prerequisites are named, so an agent would need to infer the right choice from the tool name and purpose 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 indicate read-only and non-destructive behavior. The description adds value by stating return fields (code, description, category) and search modes, providing useful context that is not in the annotations. No contradictions with annotations were found.

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 no fluff. The main action is front-loaded, and every phrase adds useful information about search modes or return values. Excellent structure.

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 lookup tool with three optional parameters and no output schema, the description covers purpose, search modes, and return fields. It could mention the default behavior when no parameters are provided, but overall it is complete enough for effective 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?

The schema provides 100% coverage with descriptions for all three parameters. The description's mention of 'exact code, code prefix, or keyword' mirrors the schema's parameter descriptions without adding new meaning beyond what is already structured. 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 opens with a specific verb and resource: 'Look up USPTO event codes used in trademark prosecution.' This clearly distinguishes the tool from generic siblings like get_reference_lookup by focusing on event codes and the trademark prosecution domain.

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 explains how to search (by exact code, prefix, or keyword) but does not provide explicit when-to-use guidance or mention alternatives. The phrase 'used in trademark prosecution' implies its context, but no exclusions or comparisons are given.

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 and non-destructive behavior. The description adds that results are based on 'most commonly follow', implying a statistical or historical source, but it does not explain what happens if no mapping exists, whether results are sorted, or if the output is a list (though the 'limit' parameter suggests multiple). It adds some context beyond annotations but lacks depth.

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, clear sentence that front-loads the key action and object. Every word is necessary and there is no repetition of schema information.

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

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

The tool is a simple lookup with a clear purpose, and the schema documents both parameters. However, with no output schema, the description does not clarify the return structure (e.g., whether it returns a single mapping or a list, or the fields included). This is a moderate gap that could confuse the agent.

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 covers both parameters fully (event_code and limit), so the baseline is 3. The description adds no additional parameter-specific details beyond what the schema already provides, such as formats or examples.

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 specifies a concrete action ('Look up') with a specific resource ('USPTO status code and status definition') and a condition ('most commonly follow a specific prosecution event code'). It distinguishes itself from siblings like 'get_event_code_reference' by focusing on status mapping rather than definition alone.

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 context but does not explicitly state when to use it versus alternatives or when not to use it. It lacks any mention of use cases, alternatives, or exclusions, so the agent must infer from the tool name and description.

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 and non-destructive behavior. The description adds valuable behavioral context by framing the output as 'circumstantial signal, not statutory fame proof' and detailing the kind of data returned (fame tier, path, etc.), helping the agent understand the nature and limits of the response beyond the safety 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 somewhat long but well-organized, front-loading the core function, followed by a structured list of returned attributes and then usage guidance. The length is justified by the complexity of a fame profile, but a few redundancies (e.g., 'brand' and 'mark wording') could be tightened.

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 complexity and the absence of an output schema, the description thoroughly covers what data will be returned (fame tier, path, footprint, portfolio size, crowding, TTAB history), how to invoke it (by mark or stem), and a critical limitation (circumstantial, not statutory proof). This makes it highly complete for an agent to understand the tool's scope.

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 sole parameter mark_or_stem has a detailed schema description (100% coverage) explaining that a mark or bare brand stem resolves to the same family. The tool description only briefly repeats this ('by mark wording or brand stem') without adding substantial new meaning, so the schema carries the semantic burden.

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 specific resource ('full fame profile for a brand'), enumerating the profile's components (fame tier, path, class footprint, portfolio size, brand-stem crowding, TTAB history). This distinguishes it from sibling tools like is_mark_famous, which presumably only returns a yes/no fame determination.

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

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

Explicit use cases are provided: 'explain WHY a mark is (or is not) famous' and 'profile a senior mark before a §2(d) / opposition / dilution strategy.' The caveat 'Circumstantial signal, not statutory fame proof' serves as a when-not-to-rely-on guidance. However, it does not explicitly name alternative tools, such as is_mark_famous, for simpler fame checks.

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. The description adds meaningful behavioral detail: it resolves/normalizes a firm name, aggregates deadlines and recent OAs from dual sources (case-file events and prosecution documents), and includes ROA-filed and §2(d) indicators. This goes beyond the basic safety profile, though it does not discuss pagination, rate limits, or exact return formatting.

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: the first packs the core function and scope, the second provides concrete example queries. Every sentence earns its place with no redundancy or 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?

For a 4-parameter, no-output-schema tool, the description covers purpose, data sources, and inclusion criteria well. It does not list alternatives or return structure, but the example questions and explicit content summary suffice for the tool's complexity. Slight gap: no mention of how results are ordered or whether both deadlines and OAs are always present.

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

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

Schema description coverage is 100%, and each parameter has a clear description with defaults and bounds. The tool description adds little to parameter semantics—only the example 'over the next 30 days' hints at deadline_days usage. Baseline 3 is appropriate since the schema carries the full burden.

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 ('Resolve a trademark law firm and return') and clearly identifies the resource ('firm correspondent tasks'). It enumerates exactly what is returned (overdue/next-window deadlines, recent Office Actions from case-file events and prosecution documents, ROA-filed and §2(d) indicators), distinguishing it from simpler firm-deadline or OA-only tools. Example questions reinforce the purpose.

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 with example questions ('what correspondent tasks should this firm focus on over the next 30 days?'). It implies when to use the tool but does not explicitly mention exclusions or alternative sibling tools, so it stops short of full 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 destructiveHint=false, but the description adds meaningful detail beyond them: the data source ('public firm resolution and prosecution mappings only') and explicit exclusions (workspace, client, reminder, user-created data). This enriches the agent's understanding of the tool's 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?

Two sentences, front-loaded with the primary verb and resource, followed by a clarifying limitation. Every word earns its place; no fluff 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 an output schema present and a read-only tool of moderate complexity (7 params, all documented), the description sufficiently covers the tool's scope, data source, and exclusions. It gives the agent enough to correctly decide invocation without needing to parse the 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?

The input schema provides 100% description coverage for all 7 parameters, including defaults and enum values. The description itself does not add parameter-specific information, but per the rubric, a baseline of 3 applies when the schema carries the load. No compensation needed.

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 the specific verb 'Get' and precisely identifies the resource: 'public, system-generated trademark deadlines across marks handled by a specific law firm.' This clearly distinguishes it from sibling tools like get_mark_deadlines and get_owner_deadlines by the firm-level 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 ('public, system-generated' and 'Does not expose any workspace, client, reminder, or user-created deadline data') that tells the agent when to use this tool and what it will not return. However, it does not explicitly name alternative tools for those excluded cases, 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is established. The description adds meaningful behavioral detail: it resolves/normalizes the firm name, computes rates at mark level, and distinguishes raw counts versus excluding pending matters. This gives context beyond the annotations, though edge cases like unknown firms or empty result sets are not disclosed.

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

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

The description is two sentences, front-loaded with the primary action, and includes illustrative user questions. Every sentence earns its place with no redundancy, making it both concise and well-structured.

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

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

With two parameters, no output schema, and annotations that confirm read-only behavior, the description supplies the essential context: what the tool computes, the distinction between raw and excluding pending matters, and example questions. It does not fully specify the exact response format, but enough is conveyed for an agent to use the tool correctly in most situations.

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% description coverage for both parameters: firm_name and limit, each with clear descriptions. The tool description does not add additional parameter semantics beyond what the schema already 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 states a specific action (resolve a law firm and compute mark-level Office Action outcome rates) and resource (firm's OA outcomes). It includes example questions that clarify intended use, and it distinguishes itself from sibling tools like get_latest_office_action (single mark) and research_office_action (likely OA strategy) by focusing on firm-level aggregated metrics.

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 questions like...' giving concrete query examples, which provides clear context for when to invoke the tool. However, it does not mention when NOT to use it or name alternative sibling tools for different scenarios, so it falls short of explicit exclusion 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 destructiveHint=false, so the agent knows this is a safe read operation. The description adds valuable context about ranking criteria (filing volume, prosecution, TTAB activity counts) and the one-firm scope, going beyond simple read-only labeling.

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: the first states the function and criteria, the second gives usage context with an example query. Every word earns its place; no redundancy or 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?

For a two-parameter tool with full schema annotations, an output schema, and explicit usage guidance, the description is complete. It covers the core purpose, ranking metrics, one-firm scope, and a practical trigger example.

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 firm_name and limit having clear descriptions in the input schema. The description adds no parameter-specific details beyond what the schema already 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 tool retrieves leading correspondents/attorneys at a named law firm, ranked by filing volume with prosecution and TTAB activity counts. It distinguishes this from sibling tools like get_correspondent_marks by focusing on firm-level ranking and specific metrics.

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 using this tool when the user asks for top correspondents at a specific firm, with a concrete example query. However, it doesn't mention alternatives or when not to use it, so it falls short of full exclusion 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, so the safe-read nature is covered externally. The description adds some behavioral detail: it returns the latest office action plus an optional latest response products, and says refusal_grounds is parsed and authoritative. However, it does not disclose edge cases such as marks with no office action or how the verified refusal grounds are derived.

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 focused sentences, front-loaded with the main action, then adding the two key value-added details: the optional response and the authoritative refusal-grounds field. 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?

With no output schema, the description usefully explains the main returned components: the latest office action, the recorded response if one exists, and the verified refusal grounds. It does not state what happens when no office action exists or give a serial-number format, but for a single-parameter read-only lookup the essential calling context is present.

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

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

Schema coverage is 100%: 'serial_number' is described as 'USPTO serial number' in the schema lob. The description restates 'trademark serial number' but does not add substantially new meaning beyond the parameter name and schema 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 identifies a specific verb ('get'), a specific resource ('latest office action'), and the input ('trademark serial number'). It also clarifies the scope by mentioning the latest response and verified refusal grounds, and the emphasis on 'VERIFIED' and 'authoritative' distinguishes this computed result from raw document 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 does not name sibling tools or state when to prefer this tool over alternatives such as analyze_prosecution_history or get_prosecution_document. There is no explicit when-to-use or when-not-to-use guidance, so an agent must infer selection from the tool name and general wording.

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, covering safety. The description adds that the summary is AI-generated and includes specific content areas, but does not disclose potential latency, cost, or that AI-generated output may be interpretive. This is acceptable given annotations but lacks deeper behavioral context.

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

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

Two sentences with no fluff. The first sentence front-loads the core purpose, and the second enumerates coverage without redundant wording. Every sentence contributes 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?

No output schema exists, but the description enumerates what the summary covers (mark details, goods/services, status, owner, prosecution context, active legal proceedings). While it doesn't describe the exact return format or error behavior, for a single-parameter summary tool, this is largely sufficient. Slight gap: no mention of what happens if the serial number is invalid or not found.

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%: the only parameter serial_number is described as 'USPTO serial number'. The description adds no additional parameter syntax or format details, staying at baseline where the schema fully handles 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 states a specific verb ('Get') and resource ('AI-generated deep-dive summary of a specific trademark'), and lists the content areas covered. This distinguishes it from siblings like get_mark_prosecution_summary (narrower scope) and lookup_trademark (basic details) by emphasizing the AI-generated, comprehensive nature.

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 a comprehensive AI-generated overview of a mark is needed, including prosecution context and legal proceedings. It does not explicitly exclude alternatives or name sibling tools, but the clear scope provides enough contextual guidance for 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?

The description adds behavioral context beyond the annotations: it discloses that deadlines are system-generated, that mark names are resolved to serial numbers first, and that no user-created data is exposed. These are meaningful details not covered by readOnlyHint and destructiveHint.

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 the primary purpose and scope front-loaded. Every clause adds useful information—scope, resolution behavior, and exclusions—with 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?

Given the output schema and annotations, the description is complete for tool selection and invocation. It covers the target resource, scope, resolution behavior, and exclusions, which is sufficient to distinguish from siblings and use the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the relationship between serial_number and subject_name (resolving a mark name to a serial first), which is not in the schema. This helps the agent decide which parameter to use.

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 it gets public, system-generated trademark deadlines for a specific mark, with a specific verb and resource. It distinguishes from siblings like get_firm_deadlines and get_owner_deadlines by emphasizing mark-specific scope and excluding workspace/client/user-created 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 for when to use this tool (for public, system-generated mark deadlines) and an explicit exclusion (not for workspace/client/user data). However, it does not name specific alternative tools, so it stops short of full 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 indicate read-only, non-destructive behavior. The description adds essential context beyond annotations by disclosing the data source limitation: 'Data comes from USPTO records, so it is only available for marks with a USPTO record — it does not query WIPO/EUIPO live.' This is a critical behavioral trait.

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 well-structured and front-loaded with the core purpose, followed by usage guidance and a caveat. Every sentence adds value with no 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?

There is no output schema, so the description carries the burden of explaining return values. It does so in detail, listing IR number, date, status, renewal, 66(a) extension, Madrid maintenance, and foreign applications/registrations with fields. Combined with the data source caveat, it is complete for a complex 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% since serial_number is described as 'USPTO serial number'. The description restates 'by serial number' but adds no new parameter semantics or format details. 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 clearly states the tool's function: 'Get the international / foreign footprint of a U.S. trademark by serial number' and enumerates specific data elements (IR number, date, status, renewal, 66(a) extension, etc.). This distinguishes it from sibling tools, none of which focus on international/Madrid filings.

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 ANY question about a mark's foreign, international, Madrid Protocol, WIPO, or EUIPO registrations,' and also provides a when-not-to-use caveat: 'it does not query WIPO/EUIPO live.' This gives clear usage direction and 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 this a safe read-only operation (readOnlyHint=true, destructiveHint=false). The description adds useful context about the output (owners ranked by footprint, wider portfolio context), but does not disclose potential heavy queries, pagination, or any caveats about the 'landscape' aggregation.

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: the first states the core action, the second provides usage context and return summary. It is front-loaded, concise, and every sentence earns its place without 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?

Despite having 5 parameters and an output schema, the description covers the essential context: it explains the output type (owners ranked by footprint with portfolio context), gives concrete examples, and the schema covers parameters and returns. The lack of extra behavior notes is acceptable given the annotations and minimal 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?

Input schema covers 100% of parameters with descriptions, so baseline is 3. The tool description adds no parameter-specific details beyond what the schema already provides; examples like 'COMET' subtly imply contains-match, but the schema explicitly documents match_mode.

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 ('Show') and resource ('owners holding marks matching a shared trademark term'), and clearly distinguishes itself from siblings by focusing on owner landscape with portfolio context. Examples like 'Which companies own a trademark for COMET?' ground the purpose.

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 includes explicit guidance on when to use the tool ('Use this for crowded owner-landscape questions...'), providing clear context. However, it does not mention alternatives or exclusions, stopping short of a full 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 destructiveHint=false, so safety is covered. The description adds context about what data is returned (status, counts, dates, milestones), but does not disclose additional behavioral traits like error handling, data freshness, or limitations. This is adequate but not exceptional given the existing 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: the first states the purpose, the second lists return contents. It is front-loaded, succinct, and every phrase adds value. No redundant or verbose language.

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 simplicity (one parameter, no output schema), the description adequately explains what the tool does and what it returns. It lists the key return categories, which is sufficient for an agent to decide whether to use it. However, it does not mention edge cases like empty results or error behavior, which would make it more 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%, with serial_number described as 'USPTO serial number.' The tool description does not add extra meaning beyond the schema, such as format requirements or examples. Since the schema already 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 clearly states the tool's function: 'Get a compact prosecution summary for a trademark serial number.' It specifies the resource (trademark serial number) and the output contents (current status, document counts, dates, milestones, key event). This distinguishes it from sibling tools like get_prosecution_timeline or get_latest_office_action, which focus on specific 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 implies usage for a quick overview ('compact summary') but does not explicitly state when to use this tool over alternatives. No exclusions or alternative recommendations are provided, so the usage context is only implied rather than clearly guided.

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 this as a safe read-only operation (readOnlyHint=true, destructiveHint=false). The description adds context about trademark registration and the two lookup modes, but does not disclose additional behavioral traits beyond what annotations provide. This aligns with the calibration where a read-only lookup with annotation coverage earns a 3.

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 core purpose, and every phrase adds value. It efficiently conveys the tool's function and its two input modes without redundancy or 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?

Given the simple tool nature, strong annotations, full schema coverage, and presence of an output schema, the description is complete. It covers the essential lookup capabilities and is sufficient for an agent to understand when and how to invoke the tool, especially with sibling tools providing related but distinct functions.

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%, with both search_term and class_numbers already described in the input schema. The description mentions the two modes but adds no extra detail about parameter syntax, constraints, or interactions. This meets the baseline for schema-covered parameters without needing further compensation from 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 clearly states the tool's purpose: getting information about Nice Classification classes for trademark registration. It distinguishes from siblings like recommend_nice_classes by focusing on lookup and search rather than recommendation, and from get_class_relationships by targeting class details rather than relationships.

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 explains the two primary usage modes: looking up specific class numbers or searching by keyword. This implies when to use the tool, but it does not explicitly mention alternatives or exclusions, such as using recommend_nice_classes for class suggestions. The context is clear enough for an agent to select this tool for direct class information needs.

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 adds caching behavior ('Results are cached for 30 days') and the AI-generated nature of the output, supplementing the readOnlyHint and destructiveHint annotations. It also outlines the analysis dimensions, which sets expectations for the response content beyond what annotations convey.

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, each adding value: purpose, content areas, and caching. Front-loaded and free of 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 one well-documented parameter and robust annotations, the description sufficiently covers the tool's behavior. The absence of an output schema is mitigated by the explicit list of analysis areas, though it could mention response format or variability, leaving a small gap.

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

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

Schema description coverage is 100%, with the parameter fully documented including format examples and prerequisite instruction. The description adds no additional parameter semantics, so the baseline of 3 applies when 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 states 'Get an AI-generated strategic analysis of a trademark owner' and enumerates five specific content areas (brand protection philosophy, litigation posture, portfolio evolution, class distribution, likely future behavior), making the purpose unmistakable and distinguishing it from sibling tools like 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 schema explicitly instructs to 'Use search_by_owner first to find the correct normalized name,' providing a clear prerequisite for correct usage. However, the description does not name alternatives for specific owner analyses (e.g., get_owner_filing_trends) nor explicitly state when not to use this tool, so it's clear but lacks 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?

The annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful context: data source (public USPTO owner resolution), nature (system-generated), and explicit exclusion of private workspace data. This goes beyond annotations by clarifying the data scope and what the tool will not return.

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 core function, and every clause adds value. No redundant information or 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 full schema coverage, an output schema, and annotations declaring safe read behavior, the description adequately covers the tool's scope and exclusions. It is complete for an owner-level read-only query tool, and the exclusion of workspace data helps avoid misuse.

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 all seven parameters fully documented, so the description does not need to compensate. The description's phrase 'across a specific owner’s marks' adds mild context for owner_name but does not add new parameter-level 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 gets public, system-generated trademark deadlines across a specific owner's marks, using a specific verb and resource. It distinguishes itself from sibling tools like get_mark_deadlines and get_firm_deadlines by emphasizing owner-level scope and public system-generated 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 implies when to use this tool: for owner-level public USPTO deadlines, not workspace/client/reminder data. It explicitly states exclusions ('Does not expose any workspace, client, reminder, or user-created deadline data'), though it doesn't name alternative sibling tools directly.

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 safety profile is known. The description adds context beyond annotations by specifying that results are yearly counts broken down by Nice class and that they reflect portfolio evolution. It does not disclose any surprising behaviors, but it adds useful detail about the output granularity.

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 purpose ('Get a trademark owner's filing trends over time'), and includes a useful secondary sentence about portfolio evolution. No redundant or filler content.

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 read-only nature, the schema covers all parameters, and annotations cover safety, the description sufficiently conveys the output (yearly filing counts by Nice class) and its interpretive value. No output schema exists, but the description outlines the key structure of the returned data.

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 three parameters have clear descriptions. The main description does not add any parameter-specific meaning beyond what the schema already provides. Baseline of 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 function: retrieving a trademark owner's filing trends over time, broken down by Nice class. It uses a specific verb ('Get') and resource, and the mention of 'yearly filing counts broken down by Nice class' distinguishes it from other owner-related tools like get_owner_ai_summary or get_owner_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 provides clear context for when to use the tool ('Shows how the owner's trademark portfolio has evolved'), which implies a use case. However, it does not explicitly name alternatives or exclusion scenarios, so it falls short of a 5. The schema parameter description for owner_name does suggest using search_by_owner first, but that is outside the main description.

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 safety is covered. The description adds behavioral context by noting results are 'most frequent' and that they reflect owner focus, but it does not describe the return format, how ordering works, or how frequency is computed. This adds some value but lacks richer 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 sentences, front-loaded with the core action ('Get...') and immediately followed by the value statement. Every word contributes to understanding the tool; there is no wasted content. This is an efficient, well-structured description.

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 list tool with two well-documented parameters and no output schema, the description covers the purpose and use case sufficiently. It could mention the output format or limit behavior, but given the simplicity of the tool and the rich sibling context (which clarifies its niche), it is complete enough.

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 owner_name and limit have descriptions). The tool description does not add significant meaning beyond the schema; it mentions the concept of owner and keywords but does not elaborate on parameter usage or relationships. Given the full schema coverage, 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 uses a specific verb ('Get') and clearly identifies the resource ('most frequent goods/services keywords for a trademark owner'). It distinguishes this from sibling owner-focused tools like get_owner_ai_summary or get_owner_filing_trends by focusing on keyword frequency. The added phrase about brand strategy and class patterns clarifies the tool's value proposition.

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 a clear use case ('useful for understanding their brand strategy and identifying class patterns') but does not explicitly state when to use this tool over alternatives or mention exclusions. It implies usage context rather than giving direct guidance, so it earns an implied-usage score.

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 beyond the readOnlyHint annotation by disclosing the evidence types used, the exclusion of agent addresses, and the confidence tiers ('high/possible'). It also warns that 'possible' results are tentative, setting clear expectations about output reliability.

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 pack a dense payload: purpose, methodology, output caveats, and usage guidance. No redundant filler; every sentence contributes meaningfully.

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 communicates what the tool returns (evidence + confidence tier) and how to interpret it. The context signals (read-only, non-destructive) align with the described behavior. For a complex analytical tool, this provides adequate context 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 coverage is 100%, so the baseline is 3. The description adds valuable guidance for owner_name by emphasizing exact-as-recorded matching and suggesting resolve_trademark_subject for ambiguity, which compensates for schema's generic description. The limit parameter is already fully documented in 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 purpose: finding entities likely related to a trademark owner via USPTO evidence, with specific signals (shared ownership history, addresses, name tokens). It distinguishes itself from sibling tools like get_owner_filing_trends or get_mark_owner_landscape by focusing on corporate family relationships.

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

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

Explicit usage scenarios are provided (analyzing corporate family, portfolio scope, affiliation between owners) and it instructs to resolve ambiguous owner names with resolve_trademark_subject first. This is precise, actionable guidance that helps an agent decide when to use this tool.

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. The description adds meaningful behavioral context: filtering/counting only qualifying target marks, separately reporting all targets attached to qualifying proceedings, and a caveat that claimed-color metadata does not prove pleading allegations. This goes 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?

Three sentences, front-loaded with the primary action. Every sentence earns its place: main purpose, filtering/reporting behavior, and a caveat with alternative. No filler or redundant restatement of schema fields.

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

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

Given 13 parameters and no output schema, the description gives a solid high-level picture of outputs: counts of filtered target marks and separate reporting of all targets. It covers key nuances (exact class-only, color caveat) and points to an alternative for deeper evidence. It does not detail all return fields, but for an analytic tool this is acceptable.

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 77%, so baseline is 3. The description adds value for target_class_match by explaining 'exact class-only questions,' and clarifies the limited evidentiary weight of color claims (relevant to target_claims_color and target_color_families). This compensates for the missing 23% and enriches parameter understanding.

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-resource combo: 'Analyze one trademark owner's TTAB enforcement in a single call.' It clearly distinguishes from siblings by emphasizing the single-call analysis and by pointing to analyze_ttab_proceeding for deeper color-evidence verification. The scope is unambiguous and not 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?

Provides clear context for use: analyzing a single owner's TTAB enforcement, including class/type/color filters and exact class-only needs. It explicitly directs to analyze_ttab_proceeding when color evidence must be confirmed in pleadings, giving a specific alternative. It lacks broader 'when not to use' guidance but is sufficient for most scenarios.

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 (readOnlyHint=true, destructiveHint=false) already establish safety, and the description adds meaningful semantic context: 'compact', the scope 'for one owner', and a caution about interpretation of totals. It doesn't describe output structure, but for a read-only stats tool with good annotations, this exceeds the baseline.

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 core action and content, and every clause adds value—no filler, no repetition of schema details.

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 compact stats tool with no output schema, the description conveys the main output categories (opposition, cancellation, appeal, role breakdowns) and gives a clear alternative for deeper analysis. A slight gap is the lack of any indication of return shape or ordering, but the listed breakdowns and warning provide sufficient 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 67%, with owner_name and year described; limit lacks a description. The description reinforces 'one owner' and 'compact' but does not add parameter-specific semantics beyond the schema. Given moderate coverage, a 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 uses a specific verb ('Get') and clear resource ('compact TTAB history for one owner'), enumerates the breakdown types (inter partes, opposition, cancellation, extension, appeal, role), and explicitly differentiates from the sibling tool get_owner_ttab_enforcement.

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 explicitly states when to use this tool versus an alternative: 'Use get_owner_ttab_enforcement for date ranges or challenged-mark/class analysis.' It also provides interpretive guidance ('Do not equate total records with initiated oppositions'), clarifying a common misuse.

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 mark the tool read-only and non-destructive. The description adds genuinely useful behavioral detail: it returns a working link, extraction/readability status, cached document text, optional excerpts, and switches to a newest-first document list when no selector is provided. 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 four sentences with no filler: core retrieval purpose, return contents, text_query usage, and serial_number fallback. Each sentence earns its place and the most important 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?

There is no output schema, so the description compensates by naming the return fields explicitly. It also explains the input-omission mode, which is essential for correct invocation. With read-only annotations covering safety and the schema documenting all parameters, 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 coverage is 86%, so parameters are already largely defined. The description adds meaning beyond the schema by identifying document_id as the stable exact selector, explaining that omitting all selectors returns a list, and clarifying that text_query produces excerpt-centered results. It doesn't add detail for max_chars, but schema bounds cover that.

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 and resource: retrieve one specific USPTO prosecution document by stable document_id, and enumerates the selectors and return fields. The fallback behavior (serial_number alone returns a pickable list) clearly distinguishes it from list_prosecution_documents and other retrieval 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 tells the agent when to use text_query (when the user asks what a document says about an issue) and when serial_number alone is sufficient, removing the need for a separate list_prosecution_documents call. It does not contrast with get_latest_office_action or research_office_action, but the single-document scope 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 and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by clarifying that the output is 'raw data without AI analysis' and describes the chronological structure, which goes beyond what annotations provide. It does not discuss limits or auth, but that is not critical here.

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 core purpose and followed by a clarifying statement about raw data. There is zero waste and it is appropriately sized for the tool's simplicity.

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

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

With one parameter, read-only annotations, and no output schema, the description provides enough to understand what the tool does and what to expect (chronological list of events). It could be more specific about scope or limitations, but it is largely complete for a simple timeline retrieval tool.

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

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

The input schema has 100% description coverage for the single parameter serial_number, which is already described as a 'USPTO serial number.' The tool description adds no additional parameter-level detail beyond confirming it is for a trademark, 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 tool's function: 'Get the prosecution timeline for a trademark' and specifies the content as a 'chronological list of office actions, responses, and key events.' It distinguishes itself from siblings by noting it provides 'Raw data without AI analysis,' setting it apart from analysis-focused tools like analyze_prosecution_history and 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 description provides clear context on when to use the tool: for raw timeline data, and indicates a when-not by saying 'without AI analysis.' However, it does not explicitly name alternative tools for analysis, so it falls short of the highest standard for explicit alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds domain context (USPTO/TTAB) but discloses no additional behavioral traits like pagination behavior, though the after_code parameter hints at 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?

A single sentence with a clear verb and a list of example table types. It is efficient and front-loaded, though the enumeration makes it slightly longer than strictly necessary.

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 lookup tool with a well-specified schema and annotations, the description conveys the core purpose and scope adequately. It doesn't explain pagination or return format, but these are not required given the schema and 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?

With 100% schema description coverage, the baseline is 3. The description does not add parameter-level detail beyond the schema; for instance, it doesn't explain the distinction between code, query, and after_code, but the schema already handles this.

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 action ('Look up') and the resource ('USPTO or TTAB reference codes and small lookup tables'), with a helpful list of example table types. It is distinct in scope from sibling tools like get_nice_classes or search_design_codes, 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 usage context: use when you need a reference code or small lookup table value. However, it doesn't state when not to use it or mention alternatives, such as more specialized sibling tools for specific tables.

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 this as read-only and non-destructive. The description adds value by explaining the matching algorithm (phonetic, trigram, component) and the meaning of similarity_score vs confusion_score, including the commercial overlap concept. This goes beyond the annotations and 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?

Three concise sentences, front-loaded with the core purpose. Every sentence adds meaningful information without redundancy or 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?

With annotations covering safety, a rich schema, and an output schema (not shown but indicated), the description still adds context about the scoring semantics and intended use case. It is complete for a search tool of this complexity, providing enough for an agent to invoke 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 covers 100% of parameters, so baseline is 3. The description adds minimal param-specific context (e.g., mark_name, limit, include_dead) but does not go beyond the schema. It mentions scores which relate to output rather than parameters, so no extra param 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 states it finds USPTO trademarks similar to a given mark name, specifying the search method (examiner-style knockout with phonetic, trigram, and component matching) and the purpose (identify potential conflicts). This distinguishes it from siblings like run_knockout_search and phonetic_search by highlighting the specialized output scores.

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 explicitly says 'Useful for trademark clearance searches,' providing a clear context. It does not mention exclusions or alternatives, but the use case is sufficiently clear for an agent to decide when to select this tool over others.

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 safety profile is covered. The description goes well beyond that by explaining output contents (per-filer live/registered/pending counts plus corpus totals), the behavior of rank_by (e.g., filings dominated by high-volume services vs success_rate surfacing quality), the necessity of min_filings to avoid skewed rate rankings, and that every response carries success_rate_percent and supplemental_percent regardless of ordering. There is 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 front-loaded with the core purpose, then systematically covers the most impactful behaviors (limit/offset, rank_by, min_filings, filer_profile) in a logical order. It is long, but every sentence contributes critical context for a tool with nine parameters and three enums. 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 the tool's complexity (9 parameters, 3 enums, nested output schema), the description is remarkably complete. It explains return contents, parameter interactions, edge cases (offset bands, min_filings floor), and even clarifies nuanced semantics like the difference between full_service and prosecution_only. Nothing an agent needs to correctly invoke the tool is left unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial meaning beyond the schema. For rank_by it explains the practical difference between 'filings' and 'success_rate' and warns about high-volume services. For min_filings it explains the default behavior and why the floor is required for rate rankings. For filer_profile it defines every enum in detail including what users mean by 'exclude the agencies/factories' and clarifies that prosecution_only is not a quality judgment. This far exceeds what the schema alone conveys.

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 a ranked filer table for a date range, filer type, and optional Nice classes.' It also gives a concrete example question ('Who are the top 10 filers in Class 9 in 2025?') that immediately clarifies the tool's scope, distinguishing it from the many sibling tools that cover filings, deadlines, or legal analytics.

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 rich usage context: it explains that a single call covers the full ranked list, that limit and offset can reach deeper bands, and it gives detailed guidance on when min_filings is required (for success_rate rankings). It does not, however, name any sibling tool as an alternative or say explicitly 'use this instead of X', so it stops 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 annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read nature is known. The description adds scope (filings, registrations, TTAB proceedings) but does not disclose any additional behavioral traits such as data granularity, default time periods, or potential response shapes. This is adequate but not rich.

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

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

The description is a single, front-loaded sentence that clearly states the tool's function without any fluff. It is concise 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 complexity (6 parameters, no output schema), the description is too sparse. It does not explain how metrics relate to parameters, what 'aggregate statistics' returns, or how to handle default vs. custom periods. The agent may struggle to know what to expect or how to construct a valid request.

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 50%, with three parameters lacking descriptions (group_by, nice_class, time_period). The tool description provides no parameter information whatsoever, failing to compensate for the gaps. The enums help somewhat, but the description adds no meaning beyond what the schema already provides.

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

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

The description clearly identifies the tool's purpose: retrieving aggregate statistics across USPTO trademark filings, registrations, and TTAB proceedings. It uses a specific verb ('Get') and resource ('aggregate statistics'), which distinguishes it from more specific analytics tools like get_owner_filing_trends or get_top_filers, though it doesn't explicitly name alternatives.

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 no guidance on when to use this tool versus sibling analytics tools. It does not mention alternatives, exclusions, or prerequisites. The metric enum in the schema implies some usage context, but the description itself offers no 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 declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the agent knows this is a safe read. The description adds valuable behavioral context by detailing the return payload (metadata, viewer link, PDF link, extraction status, document text, optional excerpts) and conditions like 'direct PDF link when available'. This goes beyond the annotations and clarifies what the tool does.

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 and front-loaded with the core action, then return details, then a usage pointer. Every sentence serves a purpose—action, output, and alternative guidance—making it concise without losing substance.

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

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

No output schema is provided, so the description must explain return values, and it does so by listing metadata, viewer link, PDF link, extraction status, document text, and optional excerpts. It also covers the prerequisite of knowing the entry number. Minor details like max_chars behavior are not mentioned, but overall the description is sufficiently complete for an agent to know 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?

The schema already documents 3 of 4 parameters with descriptive text (proceeding_number, entry_number, text_query). The description adds minimal parameter-level detail, only repeating 'query-centered excerpts' and the relationship of entry_number to get_ttab_proceeding_details, which is already in the schema. With schema coverage at 75%, the description does not significantly compensate for any gap, 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 tool 'Retrieve[s] and read[s] one specific TTABVUE filing by proceeding number and entry number', using a specific verb and resource. It also distinguishes itself from the sibling tool get_ttab_proceeding_details by noting that the entry number comes from that tool, making its purpose 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 provides a usage rule: 'Use get_ttab_proceeding_details first when the entry number is unknown.' This tells the agent when to use an alternative tool, which qualifies as explicit guidance on when to use this tool versus a sibling. No other exclusion is needed.

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

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

Annotations already cover readOnlyHint=true and destructiveHint=false, so safety is known. The description adds useful behavioral context about the return content: specific components like parties, marks, counsel, and recent filings with entry numbers and links, which is not available elsewhere since there is no 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 sentences, front-loaded with the core purpose and an em-dash list of contents, followed by targeted sibling disambiguation. Every word earns its place with no fluff 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?

Given no output schema, the description adequately hints at the return structure by naming key fields (parties, marks, counsel, recent filings with links). It also contextualizes against sibling tools. Minor omission: no mention of pagination or typical number of filings, but not essential for a raw-details fetcher.

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 for the single parameter proceeding_number is 100%, including an example format. The description does not add parameter-specific details, but the schema already fully documents it. 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, 'Get raw details for a TTAB proceeding,' and clearly delineates the scope: parties, involved marks, counsel, and recent filings with entry numbers and working TTABVUE document links. This distinguishes it from siblings like get_ttab_document (single filing) and analyze_ttab_proceeding (AI 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 description explicitly names alternatives and when to use them: 'Use get_ttab_document to read one selected filing. Use get_owner_ttab_enforcement for owner-wide distributions and analyze_ttab_proceeding for AI-powered merits analysis.' This provides clear decision 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 establish readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context about the market-wide aggregation scope and the date-window ranking behavior. It does not describe return format or pagination, but that is a minor gap given the read-only nature.

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: three sentences with no filler. It front-loads the core purpose, then provides usage criteria, exclusions, and an invocation hint. 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 read-only ranking tool with a fully documented schema and clear sibling differentiation, the description is complete. It covers what the tool does, when to use it, when not to use it, and how to pass the date range. No critical information is missing for selection or 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%, with each parameter already fully explained including date format examples and enum meanings. The description adds the useful instruction to pass the exact calendar range, but overall it does not need to compensate for parameter documentation gaps.

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 ('Rank') and names the exact resource: parties that filed TTAB oppositions (or cancellations) Board-wide. It explicitly distinguishes itself from sibling tools like get_owner_ttab_stats and get_ttab_proceeding_details by stating it is the only tool that ranks filers market-wide.

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

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

It gives clear when-to-use guidance with a concrete example question ('which party filed the most oppositions in April 2026?') and explicit negative routing ('Do NOT substitute get_owner_ttab_stats... or get_ttab_proceeding_details'). It also tells the agent to pass the exact calendar range the user implied.

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, but the description adds substantial behavioral context: market-determined fame, no per-class fame doctrine, a legal citation, the concept of using Nice class as a market proxy, and a clear caveat that this is circumstantial, not statutory proof. This goes well beyond the structured 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 well-organized: purpose, critical nuance, return fields, use cases, and caveat. It front-loads the primary action and every sentence earns its place by addressing selection, invocation, or interpretation of results.

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

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

No output schema exists, yet the description enumerates the key return fields (is_famous, famous_in_class, fame tier, market footprint, portfolio size, enforcement history), explains the market proxy, lists concrete use cases, and sets expectations with the 'circumstantial signal' caveat. This fully equips an agent to decide when to invoke and how to interpret the 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 coverage is 100%, so baseline is 3. The description adds strong semantic value to the 'class' parameter by explaining it is a 'PROXY for that market' and why market-specificity matters, which the schema's generic 'Optional Nice class number' does not convey. The 'mark' parameter isn't enriched, but the class parameter guidance is excellent.

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 ('Check whether a trademark is FAMOUS') and immediately adds the key distinguishing nuance: fame is market-specific and tested via a Nice class proxy. It also lists the returns and use cases, clearly separating it from generic lookup 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 gives explicit use cases ('Use for "is X a famous trademark?"...') and a boundary ('It is a circumstantial signal, not statutory fame proof'). However, it does not name any alternative tool (e.g., get_fame_profile) or state when NOT to use this tool, so exclusion guidance is incomplete.

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. The description adds useful behavioral details: includes stable document identifiers, working USPTO links 'when available', extraction/readability status, and types of filings. This goes beyond the schema and 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 tight sentences. The first provides a clear list of what the tool returns; the second gives a direct pointer to the sibling tool. No waste, front-loaded with the primary action.

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 list operation with a fully described schema, the description covers the key context: what is returned (identifiers, links, status, document types) and how to proceed to read a specific doc. No output schema exists, but the described return content suffices.

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 serial_number and limit are described). The description adds no new parameter-specific guidance, though it reinforces that the tool is scoped to a serial number. Baseline 3 applies because the schema already carries 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 specific verb (list) and resource (prosecution documents for a trademark serial number), and enumerates included content types. Also distinguishes from sibling get_prosecution_document by explicitly directing to that tool for reading a single 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?

Explicitly tells the agent to use get_prosecution_document for reading one selected document, clarifying the complementary relationship. However, it does not mention alternatives like get_prosecution_timeline, and lacks explicit 'when not to use' exclusions beyond the one tool.

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 and destructiveHint, so the bar is lower. The description adds value by detailing the returned fields (owner, status, filing dates, goods/services, correspondent) and highlights the correspondent usage, which is beyond what annotations provide. It does not disclose edge-case behavior (e.g., not-found handling), but this is minor for a read-only 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 a single, front-loaded sentence that lists key returned data and a specific use case. There is no redundancy or filler; each clause earns its place, and the 'use this for' parenthetical is directly actionable.

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 is simple (one parameter) and has an output schema, so the description does not need to explain return values. It covers the core purpose, key data fields, and a prominent use case. Given the low complexity and rich schema/annotations, the description is complete enough for an agent to select and 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 coverage is 100%: the description's wording 'by its serial number' aligns exactly with the parameter schema, which already explains the format and constraints. The description adds no new semantic information about the parameter, 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 clearly states 'Get detailed information about a specific USPTO trademark by its serial number,' which is a specific verb-resource pair. It distinguishes itself from siblings by listing the types of information returned (owner, status, filing dates, goods/services, correspondent) and the targeted use case for correspondent questions.

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 guidance for when to use the tool, specifically for 'which firm represents/is correspondent for' questions. However, it does not mention exclusions or explicitly name alternative tools for other scenarios, so it lacks the 'when-not-to-use' clarity of a fully scored guideline.

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, openWorldHint=false, and destructiveHint=false, covering the safety profile. The description adds behavioral detail beyond that: the algorithm's limitation with multi-word marks and the explicit warning that thin/empty results are not evidence of absence. It could further disclose pagination or output format, but output schema covers return shape.

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 longer than average but every sentence carries weight: it defines the matching method, states a concrete limitation with an example, and gives an explicit routing instruction. The opening sentence is front-loaded with purpose, and the LIMITS section is structured logically. Slightly verbose but justifiably so.

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 complexity of a semantic search tool, the description addresses the key pitfalls (whole-mark scope, empty-result interpretation) and directs to the clearance engine. The output schema covers result shape, and the description covers behavior. It does not state how similarity_threshold affects result count in practice, but the threshold definition is evident enough. Overall well-rounded.

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 40%, so the description partially compensates by explaining the whole-mark similarity threshold concept, but it does not explain each parameter's semantics (e.g., include_dead, nice_classes, limit). The description focuses on the mark_text and similarity_threshold indirectly; the remaining parameters rely on the schema's own brief descriptions, leaving some gaps.

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 specific verb+resource (finds trademarks whose whole mark sounds similar), names the algorithm (Metaphone + trigram) and threshold semantics, and clearly differentiates from siblings like search_trademarks and run_knockout_search by emphasizing whole-mark whole-mark comparison.

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 (sound-alike whole mark queries) and when not to (multi-word containment scenarios), and routes the agent to the alternative run_knockout_search for clearance/availability questions. The negative instruction about thin results never supporting availability conclusions is a strong usage guardrail.

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 agent knows this is a safe read operation. The description adds that it returns 'the most relevant classes with confidence scores and explanations,' but it does not disclose how relevance is determined or any other behavioral traits beyond the output format. 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?

Two sentences, front-loaded with the core action, and no filler. Every word earns its place, making this a model of concise description.

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 2 well-documented parameters and no output schema, the description sufficiently explains the input (business description) and output (relevant classes with confidence scores and explanations). It could mention how many classes are returned or how the optional industry parameter affects results, but these are nice-to-have rather than 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%, with both parameters (business_description and industry) fully described, including a minLength and instruction to pass the full user description. The description itself adds no extra parameter-level detail, so it matches the baseline expected when schema carries the load.

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 clearly ties it to an input condition ('based on a business description'). This distinguishes it from sibling tools like get_nice_classes (which likely retrieves class data) and suggest_gs_descriptions (which suggests goods/services descriptions).

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 user has a business description and needs relevant trademark classes. However, it does not explicitly mention alternatives or exclusions, so it stops short of a full guidance score.

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 readOnlyHint=true, and the description adds valuable behavioral context beyond that: the tool launches asynchronously for authenticated users, typically takes 1-2 minutes, and returns a processing handle for later retrieval. This meaningfully informs the agent about latency and result handling without contradicting the read-only 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, front-loaded with the primary action and output summary, followed by the key asynchronous behavior. Every sentence contributes useful information with no repetition or 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?

For a read-only research tool with one well-documented parameter, the description covers the return payload categories and the async retrieval flow. A minor gap is that it does not name the specific follow-up mechanism or endpoint used to retrieve the completed result via the processing handle, but this is not a critical omission 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 the single parameter serial_number is already fully documented. The description does not add extra meaning about the parameter's format or constraints, which is acceptable given the high schema coverage, but it also provides no bonus semantic 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 states a specific verb and resource: 'Research the Office Action for a trademark' and enumerates concrete outputs such as structured refusal categories, cited marks, and third-party registrations. It is clear and distinct in scope, though it does not explicitly differentiate itself from sibling tools like get_latest_office_action 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 verb 'Research' and the focus on Office Action context, but the description offers no explicit when-to-use guidance, exclusions, or references to alternative tools among the many siblings. It gives some context but leaves selection between this and similar OA-related tools to inference.

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

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

Annotations already cover read-only and non-destructive behavior. The description adds value by disclosing an authentication requirement for specific entity types and indicating the output is a 'best match,' which goes beyond the structured annotations and provides useful behavioral context.

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

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

The description is two sentences: the first states the core purpose, the second adds a critical prerequisite. Both sentences are necessary and information-dense, with no filler or repetition. It is front-loaded with the primary action.

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 handles multiple entity types and has no output schema, yet the description does not clarify whether it returns a single best match or a list of candidates. The 'limit' parameter implies multiple candidates, but the description says 'best match' (singular), creating ambiguity. It could be more complete by describing the response structure or matching confidence.

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%, with each parameter already described in detail. The description adds no new parameter information beyond what the schema provides; it essentially restates the enum values. Baseline 3 is appropriate because the schema carries the full weight.

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 resolves an ambiguous name to the best trademark entity match, listing concrete entity types (owner, firm, correspondent, mark, TTAB proceeding, client, portfolio). This distinguishes it from sibling search/lookup tools by focusing on disambiguation rather than raw searching.

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 resolving ambiguous names and adds a key prerequisite: 'Resolving clients and portfolios requires authentication.' It does not explicitly compare to alternatives or state when not to use, but the entity-type scope and auth note provide clear contextual 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 mark this as read-only and non-destructive, and the description adds substantial behavioral context beyond that: it is the same engine GleanMark uses, it returns a dead-mark 'naming territory' sample, it has a calibrated four-tier verdict, and it reports measured timing (live-only 23s vs include_dead 150s then failed). 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 dense but every sentence earns its place: purpose, scope, output, parameter guidance, exclusions, timing, and user communication. It front-loads the core function and immediately establishes the USPTO-conflict-search scope, so an agent can act on it without wading through 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?

For a complex 7-parameter search tool with no output schema, the description tells the agent what the tool does, what it returns, how to tune the key parameters, how long it takes, and which sibling handles the complementary use case. The schema covers the remaining parameter mechanics, and the description covers invocation behavior and result interpretation.

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 has 100% parameter coverage, the description adds meaning beyond the schema: goods_description is tied to risk-band behavior ('identical mark in a related-goods class reads VERY_HIGH only when the goods are supplied'), include_dead is given a strong default recommendation with measured performance data, and owner_name's portfolio-context purpose is clarified.

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: 'Run an examiner-style knockout search with scoring via the unified knockout engine.' It then enumerates the exact scope ('PURE USPTO conflict search over 14M trademark records') and output ('4-tier risk-grouped results'), which clearly differentiates it from siblings like check_brand_availability and check_domain_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 explicitly states when to use the tool and when not to: it does NOT check domain or brand availability, and directs the agent to check_brand_availability for that. It also gives decision rules for goods_description ('ALWAYS pass... when the user has told you what they sell') and include_dead ('LEAVE IT FALSE'), plus a pre-call user heads-up about timing.

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