ClaimHit

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

Adds substantial behavior beyond the annotations: it SPENDS 1 CHART CREDIT, the unconfirmed call runs nothing and returns a quote naming the matched target, and generation only happens on a second call with confirm: true. This is exactly the cost/commitment disclosure an agent needs before invoking a non-idempotent, billable write.

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 purpose followed by cost/confirm mechanics and usage triggers, with essentially no filler. Minor redundancy: the confirm two-step is restated in the confirm parameter's own schema description, so a little space is spent twice.

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 billable, two-phase tool with no output schema, it covers the trigger, the cost, and the confirm handshake, plus what the unconfirmed call returns. It does not say how the finished chart is retrieved (presumably via claimhit_get_result), leaving one small linkage 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%, so all three parameters are already documented in the schema, including the confirm gating semantics and the target_name format examples. The description reinforces the confirm flow but adds no new syntax or format meaning, so 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?

States a specific verb and resource ('Generate an AI Hit Chart') plus its scope ('for a specific target (product or standard) from a previous search') and defines what a Hit Chart is. This clearly separates it from siblings like claimhit_search (which finds targets) and claimhit_get_result (which retrieves output).

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 explicit trigger conditions ('Use this when the user asks to chart, map claims, or analyse a specific target in detail') and spells out the two-step confirm precondition. It does not name a competing sibling or state when NOT to use it, so it falls short of full 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context by specifying the two credit types (search and chart), which goes beyond the title. No contradictions or missing side-effect warnings.

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 is front-loaded with the verb and resource. Every word earns its place, with no fluff or redundancy.

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

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

Given the tool's simplicity (no parameters, no output schema, clear read-only intent) and the strong annotations, the description is complete enough for an agent to select and invoke it correctly. It clearly states what the tool returns (credit counts) without needing additional detail.

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

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

The tool has zero parameters, so the input schema is empty; the description fully compensates by explaining what is being checked (remaining search and chart credits). This gives the agent complete understanding of the tool's purpose without needing parameter details.

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

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

The description uses a specific verb ('check') and resource ('search credits and chart credits'), clearly distinguishing this tool from siblings that generate charts, retrieve history, run searches, or rerun searches. The scope is precise and immediately understandable.

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 makes it obvious this tool is for checking remaining credits, which is distinct from the other tools' actions. It doesn't explicitly state when not to use it or name alternatives, but the context makes the usage clear, and no exclusions are needed for such a simple read-only query.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds that it returns patent numbers, dates, and top results, giving some behavioral context, but does not elaborate on ordering, time window, or other details.

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?

Single sentence, front-loaded with verb and resource, no redundant words. It is approximately 14 words, making it perfectly concise and easy to scan.

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 one-parameter history tool with comprehensive annotations and schema coverage, the description sufficiently communicates functionality and return fields. There is minor ambiguity around 'top results', but overall it is complete enough for an agent to select and 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?

The only parameter 'limit' is fully documented in the schema (default 5, max 20), so the description does not need to add anything. Schema coverage is 100%, meeting the baseline of 3.

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

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

The description uses a specific verb 'Get' and resource 'user's recent patent scans', and explicitly lists return contents (patent numbers, dates, top results). This clearly distinguishes it from sibling tools like search (new searches) and get_result (specific result).

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 establishes clear context as a history/listing tool, implying it should be used for viewing past scans rather than performing new ones. However, it does not explicitly name alternatives or provide exclusion criteria, but the context is strong enough to guide selection.

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

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

Annotations only establish read-only/idempotent safety; the description adds the genuinely non-obvious traits: calls are free and unlimited, enrichment continues for minutes after first results, and results are incomplete while a `more` field is present. Those are exactly the behaviors an agent would otherwise get wrong.

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

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

Front-loaded with purpose and cost model, then the two failure modes (RUNNING status, `more` paging) as separate sentences. Slightly long for its content, but every sentence carries an actionable instruction.

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

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

With no output schema, the description supplies the key return-field semantics (status, more) and the paid-vs-free boundary against Hit Charts. It does not describe the shape of a target record itself, which for a 10-parameter read tool is the main remaining gap.

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

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

Schema coverage is 100% and each parameter has its own explanatory description, so the schema does the heavy lifting. The description adds only indirect parameter guidance (consult `status`, use the offset from `more`) rather than explaining the filter/sort/detail options. 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?

States a specific verb and resource — retrieve results of a previous search by search ID — plus the transformations it supports (narrow, sort, page). It is clearly distinguishable from claimhit_search (which creates the search) and from claimhit_get_history without needing the sibling schemas.

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 says when to call repeatedly ('filter and re-read as much as the conversation needs'), when to poll again (status RUNNING), and when results may be treated as final (COMPLETE). It doesn't contrast with claimhit_rerun_search or claimhit_get_history for the case where results are stale, which is the one open routing question.

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

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

Annotations already declare readOnly/openWorld/non-destructive/idempotent=false, and the description adds real value beyond them: output cardinality ('up to 5 real, current products with a reason for each'), grounding method ('live web search'), and cost ('FREE: no credit is taken'). It stops short of covering failure modes (e.g. what happens with a vague instruction or how exclusions from prior results interact), so it is strong but not exhaustive.

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

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

Front-loads the action, then inputs, outputs, cost, and sibling routing in a tight package. Every clause does work — the cost note and the charting/search routing are both decision-relevant, so no sentence is padding.

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

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

With no output schema and only three parameters, the description carries the return-value burden and does so ('returns up to 5 real, current products with a reason for each'), plus grounding, cost, and when to call it. An agent has everything needed 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 coverage is 100%, so the baseline is 3, but the description adds semantic framing the schema lacks: it explains the pairing of 'a vague or wrong target' with 'what the user wants instead' and enumerates instruction types (model, version, capability, market) with examples. It clarifies intent-shape rather than just restating field names.

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

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

Specific verb ('Look again at one target from a search') plus explicit scope ('It refines one row'), and it names the contrasting sibling: 'to screen a whole market for a patent, use claimhit_search.' An agent can distinguish this from every sibling without opening a schema.

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

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

Gives a concrete when-to-use ('Use it before charting, to chart the right thing') and an explicit exclusion/alternative ('It refines one row; to screen a whole market for a patent, use claimhit_search'). Nothing is left to inference.

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

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

Annotations cover only the safety/state profile (readOnlyHint=false, idempotentHint=false), so the description carries the real behavioral burden and does so well: cost model (free within 6 months, 1 credit after), a two-phase quote-then-confirm flow, and an explicit guarantee that nothing runs or is charged without confirm:true. This is exactly the context an agent needs before triggering a charged operation.

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 tight sentences, front-loaded with purpose, then cost, then the confirmation mechanic, then the sibling redirect. Every sentence carries distinct, decision-relevant information 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?

No output schema exists, but the description still explains the return shape of the unconfirmed call (a quote listing repeated inputs and free/paid status), plus the cost and confirmation semantics. For a 3-parameter, charged re-run tool this is 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the field docs by framing confirm as part of a quote-approval workflow and by clarifying that the scope inputs (company scope, hint, products, markets, sizes, standard) are repeated from the original search rather than supplied again. That framing materially affects how an agent should present the call to a user.

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

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

States a specific verb and resource ('re-run a previous patent search') and enumerates the scope it repeats, so it is immediately distinguishable from claimhit_search (new search) and claimhit_get_result (read existing results). No ambiguity about what the tool does.

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

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

Explicitly routes the agent: re-run here, but use claimhit_get_result to narrow or re-read existing results, which is called out as free and non-initiating. The widen parameter guidance ('use when the first search was scoped to named companies and found too little') gives a concrete condition for the main branch.

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 behavior beyond annotations: it reveals parallel execution of multiple AI models and the return of ranked results with Hit Scores. It also uses 'potentially infringe' to set probabilistic expectations. Annotations provide openWorldHint and non-read-only hints, but the description enriches the agent's understanding of how the tool operates, though it does not mention cost/credit consumption.

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, front-loaded sentences: purpose first, then behavioral detail, then usage guidance. No filler or redundancy. Every sentence adds value, making it easy for an agent to parse quickly.

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

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

For a 4-parameter tool with no output schema, the description covers purpose, behavior, and usage context. It mentions the return format ('ranked results with Hit Scores') which is a minimal but acceptable descriptor. However, it lacks details on pagination or how results might be retrieved later (sibling get_result hints at persistence), leaving some gaps 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% with detailed parameter descriptions (examples, defaults, enums). The description adds no extra parameter semantics beyond confirming products/standards which aligns with the 'mode' parameter. Baseline 3 is appropriate because the schema carries the full semantic 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 ('Search'), identifies the resource ('a given patent'), and defines the scope ('products or technical standards') with clear intent ('potentially infringe'). It differentiates from siblings by mentioning parallel AI models and Hit Scores, and the usage cases (find infringers, check infringement, screen a patent) distinguish it from claimhit_get_result or claimhit_rerun_search.

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 this tool: 'when asked to find infringers, check infringement, or screen a patent.' This is clear context, but it does not mention alternatives or exclusions, failing to reach the level of explicitly naming sibling tools for different scenarios.

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