Hathitrust

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

Annotations already mark it safe (readOnly, idempotent, non-destructive). Description adds cost context (free default model, BYO key for Anthropic) and behavior (returns per-model data with combined view).

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?

Concise yet thorough: first sentence defines core action, second covers defaults and options, third describes return format, fourth lists use cases. No wasted text.

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, but description fully explains return structure (per-model fields + combined view). All 4 parameters documented in schema, use cases covered, no missing information.

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. Description adds value by specifying default model, free usage, and the role of context in disambiguation.

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?

Clearly states the tool probes LLMs for entity visibility and outputs a score (0-100) per model. Differentiates from sibling tools by focusing on AI-marketing audits and brand checks, not general knowledge 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?

Explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Explains default model and optional API key for Anthropic, but does not contrast with sibling 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, openWorldHint, idempotentHint, and destructiveHint false. The description adds meaningful behavioral context beyond these: it routes to one of 5,798 tools, fills arguments automatically, and returns structured answers with stable citation URIs. It could further disclose latency, failure behavior, or fallback behavior, but the existing disclosure is solid.

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

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

The description is long but information-dense and front-loaded with the most important guidance ('PREFER OVER WEB SEARCH'). The examples and source list earn their place, but there is mild redundancy between the 'Use whenever' phrasing and the earlier 'prefer over web search' instruction, so it is not perfectly concise.

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

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

For a single-required-parameter tool with no output schema, the description provides enough context: when to use, what to ask, what happens internally, and what kind of output to expect. It could more precisely describe the response structure, but the 'structured answer with stable pipeworx:// citation URIs' statement gives adequate grounding.

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

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

Schema coverage is 100% and the schema clearly documents the 'question' parameter and its aliases. The description adds value by showing the range of acceptable natural-language questions, providing category examples, and explaining that the tool itself fills arguments. This exceeds the baseline for high schema coverage.

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

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

The description clearly states that the tool answers factual questions by routing them to authoritative data sources and returning structured answers with pipeworx:// citations. It distinguishes itself from web search and Deep Research, but it does not differentiate itself from the closely named siblings ask_pipeworx_beta and ask_pipeworx_grounded, so the purpose clarity is strong but not perfect.

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 prefer this tool over web search for factual/current/historical questions, gives trigger phrases like 'what is', 'look up', 'find', and 'get the latest', and explicitly directs general knowledge or open-ended research to Deep Research instead. This is clear, actionable guidance with an explicit alternative.

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/idempotent annotations, the description discloses genuinely useful behavioral traits: live candidate routing 'enabled live whenever one is under test', the current no-candidate state making it identical to stable, and the misconception-correction 'Falls back to nothing — this IS a full working router, just the experimental edge.' No contradiction with annotations; the experimental-state context adds real value.

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

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

Four sentences, each earning its place: identity, current state, usage instruction, and misconception correction. The description is front-loaded with the core identity. The very specific date '2026-07-26' will age poorly and could confuse later, which prevents a 5.

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

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

For a low-complexity tool (one real parameter, no nested objects), the description covers identity, current operational state, usage, and experimental consequences. The 'same response shape' phrase reasonably defers output details to the sibling tool's documentation, though a fuller description of what the router returns would make it fully 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?

Schema coverage is 100% — all six parameters are documented as aliases for 'question', with the question parameter itself well-described in the schema. The description adds only the meta-note 'same arguments' pointing at ask_pipeworx, which confirms parameter equivalence but provides no additional semantic meaning. 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 states a specific identity: 'Beta version of ask_pipeworx: identical universal router (same 5,798 tools, same arguments, same response shape)' with the distinguishing experimental-routing angle. It clearly separates this from the stable ask_pipeworx sibling and other tools by framing it as 'the experimental edge' of an otherwise identical router.

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 guidance is given: 'Use it exactly like ask_pipeworx when you want the newest routing.' This names the alternative tool and the selection condition. It lacks an explicit when-not-to-use exclusion, but the conditional phrasing makes the choice criterion clear enough that an agent can route correctly.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), so the bar is lower, but the description adds substantial behavioral context: the exact success return shape with evidence and confidence, the explicit refusal contract with the full refusal_reason enum, and the cost/LLM-call behavior. This is exactly the transparency an agent needs to avoid acting on fabricated answers.

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

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

The description is long but every clause earns its place: mode identity is front-loaded, followed by the routing pipeline, return contract, refusal contract, usage guidance, and cost comparison. The full refusal enum listing is verbose but valuable given there is no output schema. Slightly dense, but not wasteful.

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

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

For a one-required-parameter question-answering tool with no output schema, the description is complete: it documents the return shape, the refusal behavior and all refusal reasons, the cost tradeoff, when to prefer the alternative, and the high-stakes usage context. Nothing an agent needs to call it correctly or interpret its response is missing.

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

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

Schema description coverage is 100%, with the single 'question' parameter and all six aliases documented in the schema itself. The description adds context about what happens to the question (routing across 5,798 tools, filling arguments) but no additional parameter-level semantics. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description states a specific verb and resource: 'Hallucination-resistant answer mode' that routes to the right tool and 'EXTRACTS the answer using ONLY what the tool result contains.' It explicitly names the sibling ask_pipeworx and contrasts the routing behavior, so an agent can distinguish grounded mode from the casual mode without opening the schema.

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

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

Provides explicit when-to-use criteria: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also gives the exclusion rule and alternative: 'prefer ask_pipeworx for casual lookups,' backed by the cost difference of one extra LLM call.

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 indicate read-only, open-world, and idempotent behavior. The description goes far beyond by detailing fan-out logic, response shapes, resolution contract (market_match_confidence, alternatives, suggestions), parent event extraction, news fallback handling, safety mechanisms (low-confidence short-circuit, closed market detection, wide spread warnings), and resolution-rule risk analysis. This provides agents with comprehensive understanding of the tool's behavior.

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

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

The description is very detailed but quite lengthy, spanning multiple paragraphs. While it is well-structured with clear sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.), it could be more concise. The front-loading of purpose is good, but the volume of detail may overwhelm some agents.

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 the tool (multiple data sources, fan-out, response handling, error states) and the absence of an output schema, the description is exceptionally complete. It covers input, output, edge cases (low confidence, closed markets, wide spreads), resolution rules, and fallback behavior, leaving minimal ambiguity.

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 schema coverage is 100%, the description adds significant value by explaining the market parameter's three allowed formats, the depth parameter's two options with default, and the include_raw parameter's impact on response size. It contextualizes how each parameter affects the tool's execution and output.

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: researching a Polymarket bet by pulling Pipeworx data. It specifies the types of input (slug, URL, question text) and the output (evidence packet, market-vs-model comparison). This distinguishes it from sibling tools, which are focused on other tasks like arbitrage, edge tracking, or general queries.

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 usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' While it does not mention when not to use or alternative tools, the examples are clear and actionable.

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

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

The description adds 'Keyless' meaning no API key required, and explains the output: existence, count, and URLs. These details go beyond annotations (readOnlyHint, idempotentHint) by clarifying the no-auth aspect and the type of response.

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-loading the purpose ('Convenience check') and clearly stating the action and output. No extraneous 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?

Given no output schema, the description adequately describes the return value (existence, count, URLs). However, it could mention handling of invalid identifiers or edge cases, but overall it is sufficiently complete for a simple check 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 coverage is 100% with descriptions for both parameters. The description does not add additional semantics beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: given an identifier, it checks for readable full-view scanned copies on HathiTrust and reports counts and URLs. It is specific and distinct from typical lookup tools by emphasizing 'convenience check' and 'keyless'.

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 uses 'Convenience check' which implies a lightweight use case, but it does not explicitly state when to use this tool versus siblings like 'get_record' or 'lookup_by_identifier'. No exclusions or alternatives 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?

Discloses data sources (SEC EDGAR, FAERS), handling of off-calendar fiscal years, sorting behavior by primary metric, and output format with citation URIs. Annotations already cover read-only, idempotent, non-destructive nature, and description adds substantial 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?

Highly concise: 5 sentences packed with essential information. Front-loaded with example queries. No redundant or unnecessary text. Every sentence serves a clear purpose.

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 2 parameters, no output schema, and existing annotations, the description fully covers tool behavior, data sources, sorting, and expected output. An agent can confidently decide when and how to invoke this 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?

Adds significant meaning beyond schema: explains that type='company' pulls latest 10-K data, type='drug' pulls FAERS data, and values examples are given. Schema coverage is 100% but description enriches understanding of what each parameter value entails.

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 clearly states it performs side-by-side comparison of 2-5 entities, with specific examples of query patterns and data sources. Distinguishes from sequential lookups by emphasizing parallelism.

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 instructs to prefer this tool over sequential single-pack lookups when comparing entities. Provides clear context for when to use each type (company vs drug) with concrete data sources.

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 carry readOnlyHint=true, openWorldHint=true, and idempotentHint=true, so the bar for added value is higher — and the description clears it substantially. It discloses that findings are grounded with verbatim evidence and confidence scores, that gaps[] are explicit and never invented, that citation_uris are only present when actually resolvable via resources/read, that standard/thorough include a contradictions[] scan, that large records are semantically excerpted rather than head-truncated, and that latency ranges from 15-60s up to ~90s. This is rich behavioral context well beyond the annotations, and nothing contradicts the read-only/open-world/idempotent hints.

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

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

The description is long (roughly 270 words) but nearly every sentence earns its place given the tool's complexity: auth, routing decision, scope, output shape, depth semantics, latency. It is front-loaded with the most consequential constraint (ACCOUNT REQUIRED). It loses a point for being a dense single wall of text with some redundancy between the prose depth explanation and the already-detailed schema enum description; light restructuring or trimming of the second-hop paragraph would make it a 5.

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

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

There is no output schema, so the description correctly carries the full burden of explaining the findings-packet return shape — verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, hop field, citation_uri resolvability, gaps[], contradictions[]. Combined with the annotations and a fully-documented input schema, there is no missing information an agent needs to decide whether to call this tool or to interpret its response.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description adds value beyond the schema by attaching behavioral consequences to depth — thorough costs money, thorough can take up to ~90s, quick is single-hop, standard/thorough do gap-recovery and contradictions[] — and by illustrating what makes a good question ('Broad/multi-part is fine — decomposition is the point' is schema, but the compare/regulatory examples are description). This exceeds the baseline slightly, so 4 is appropriate rather than 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 names a specific verb and resource ('Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources... in ONE call') and clearly states the mechanism: decompose into facets, route to 5,798 tools in parallel, return a findings packet. It explicitly differentiates itself from open-web search and from ask_pipeworx, and gives concrete example questions. An agent can confidently 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?

Explicit when-to-use guidance is present: 'Best for broad/multi-part questions over structured data' with two worked examples. Alternatives are named with selection conditions: 'For a single lookup use ask_pipeworx' and 'If you are not signed in, use ask_pipeworx instead — it works on every tier.' The account/paid-plan prerequisite is stated up front, so an agent can route around auth failures.

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, idempotent, non-destructive behavior. The description adds that results come with full input schemas and curated examples, ready to call directly. No contradictions. Points deducted for not mentioning any implicit side effects or auth needs, but these are minor given the annotations.

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

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

The description is front-loaded with the main purpose, followed by examples and a succinct statement of return value. It is moderately long but every sentence serves a purpose. Minor improvement could be trimming the list of domains, but overall 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?

Given no output schema, the description adequately covers return format (names, descriptions, schemas, examples). It explains the limit parameter's default and max, though not in description itself (in schema). The description is complete enough for an agent to use the tool effectively.

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

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

Schema description coverage is 100%, so the schema itself documents all parameters well. The description does not add significant meaning beyond noting 'top-N most relevant tools' and readiness. Baseline 3 is appropriate as the description does not deepen understanding of parameters beyond 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 'Find tools by describing the data or task' and enumerates specific domains like SEC filings, FDA drugs, etc. This distinguishes it from sibling tools, which are task-specific (e.g., deep_research, entity_profile).

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 advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Also lists use cases (browse, search, look up) and provides concrete examples, leaving no ambiguity about when to invoke.

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 far beyond the readOnly/openWorld/idempotent annotations by detailing the fan-out across SEC EDGAR, XBRL, USPTO, USAspending, Purple Book, DOL LCA, GDELT/GNews, and GLEIF. It also explains sources_used/sources_failed semantics, fallbacks, and empty-section behavior, giving the agent a rich model of what will happen.

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 purpose and usage, but it is a long, dense paragraph with several parenthetical asides. Still, every clause carries operational value, especially given the absence of an output schema, so the length is largely justified.

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 fully compensates by enumerating all returned sections, including recent_filings URIs, fundamentals, patents, federal_contracts, fda_products, hiring, news, and LEI. It also covers failure modes and expected empty results, leaving little ambiguity for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful extras: concrete examples for tickers, CIKs, and company names, zero-padded CIK convention, resolved_from/resolved_to behavior, and the private-company edge case. It does repeat some schema text, but the added examples and resolution semantics justify the bump.

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 exactly what the tool produces: a 'full cross-source profile of a US public company in ONE parallel call.' It opens with concrete user utterances and explicitly distinguishes itself from single-pack SEC/XBRL/news lookups, making the tool's purpose unmistakable.

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

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

The description gives an explicit directive: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies the accepted input forms and how private companies are handled, which helps an agent decide when this tool is appropriate.

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 provide destructiveHint=true and idempotentHint=true. The description confirms 'Delete' but adds no additional behavioral context beyond that.

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

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

Two sentences, no wasted words. The purpose and usage are front-loaded and clear.

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?

Simple tool with one parameter and no output schema. The description covers action, when to use, and sibling tools. No gaps for a memory deletion function.

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?

Single parameter 'key' is documented in the schema with 'Memory key to delete'. The description mentions 'by key' but adds no extra meaning beyond schema coverage of 100%.

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

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

The description clearly states 'Delete a previously stored memory by key' – a specific verb and resource. It distinguishes itself by mentioning sibling tools 'remember' and 'recall'.

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 scenarios: 'Use when context is stale, the task is done, or you want to clear sensitive data.' Lacks explicit when-not-to-use but still strong 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 (readOnlyHint, idempotentHint, destructiveHint) already declare safety. Description adds value by explaining the exact actions (fetches, extracts, emits) and output format, reassuring the agent about behavior without contradiction.

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

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

Three efficient sentences: front-loads purpose, explains process, lists use cases. No wasted words, well-structured for quick comprehension.

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 parameters and no output schema, the description covers purpose, process, output format, and use cases adequately. Slight gap on error handling or limitations, but overall complete enough for its 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 coverage is 100% with clear parameter descriptions. The description does not add new information about parameters beyond what the schema provides, so 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 generates a production-ready llms.txt file for any URL, detailing the process (fetches page, extracts info) and output format. It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing specifically on llms.txt generation.

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 lists three use cases: getting a client's site indexed, drafting for own project, auditing competitors. While it doesn't mention alternatives or when-not-to-use, the positive guidance is strong and context-rich.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to repeat safety. It adds value by detailing the return content (full bibliographic metadata and flagged scanned copies), which goes beyond annotations.

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

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

The description is a single sentence with an example, front-loading the purpose and key details. No unnecessary words.

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 annotations covering safety and idempotency, the description provides sufficient detail about the return value (metadata and scanned copies). No output schema exists, so the description adequately explains what the tool returns.

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

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

Schema coverage is 100% for the single parameter, which is already well-described in the schema. The description adds an example and mentions 'Keyless' (likely implying no auth needed), but this is not about parameter semantics. 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 it gets a single HathiTrust catalog record by record number, listing the full structured metadata and scanned copies with access flags. It distinguishes from sibling lookup_by_identifier by specifying how to obtain the record number.

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 an example and mentions that record_number can be obtained from lookup_by_identifier, giving context for when to use it. However, it does not explicitly state when not to use it or list alternative tools for similar tasks.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds value by listing returned fields and implying active subscriptions, no contradictions.

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

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

Two efficient sentences with no wasted words. Front-loaded with purpose, then guidance.

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?

Sufficient for a list tool with one optional parameter. Lists returned fields despite no output schema.

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

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

Schema covers the single parameter with description. Description does not add additional meaning beyond schema, 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?

Description clearly states 'List the caller's active subscriptions' with specific verb and resource. Distinguishes from sibling tools like 'subscribe' and 'unsubscribe'.

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 usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Could be improved by noting when not to use.

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 indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, confirming safe read-only behavior. The description adds behavioral detail by stating the tool returns 'every scanned copy, each flagged full-view or limited based on its rights code,' which is beyond what annotations provide. No contradictions.

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

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

The description is two sentences, immediately front-loading the purpose and supported identifiers. Every word adds value (e.g., 'keyless', '18M+ volumes', 'full-view or limited'). No redundancy, ideal length for quick comprehension.

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 (two parameters, no output schema), the description adequately covers what it does and what it returns. It mentions rights-based access flags, which is useful. It doesn't need to explain return format since no output schema, but could briefly mention potential result count. Still, fairly complete for a straightforward lookup 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% (both id and id_type have descriptions). The description lists the identifier types (OCLC, LCCN, ISSN, etc.), which matches the schema enum, and adds context about the returned data. However, it doesn't significantly add new meaning beyond the schema; it reinforces what is already present.

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: looking up HathiTrust's digitized-book holdings by a standard identifier. It lists specific identifier types and what is returned (bibliographic records and scanned copies). This tool is distinct from siblings like search_within or get_record, and the description immediately conveys its specific use case.

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

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

The description mentions it is 'keyless' and covers 18M+ volumes, which implies ease of use, but it does not explicitly state when to use this tool versus alternatives like search_within or get_record. There is no guidance on when not to use it or which identifier type to prefer for different 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 provide no safety hints (all false), so the description carries the burden. It discloses the claim_token flow, rate limit (5/day), free usage, no quota impact, and that the team reads digests daily. This goes well beyond the structured annotations and adds valuable operational context.

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

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

Although long, every sentence earns its place. The description is front-loaded with purpose, then usage, exclusions, claim_token behavior, and limits. No filler or repetition; the length is appropriate for the tool's complexity.

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

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

With no output schema, the description must explain return behavior. It does: filing without an account returns a claim_token, and passing it back later returns status and resolution details. It also covers rate limits and scope, making the tool fully self-contained for an 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?

Schema description coverage is 100%, so the baseline is 3. The description adds extra nuance about the claim_token: filing without an account returns a token, and you can pass it back later to check status. This is not explicitly in the schema, so it deserves a 4.

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

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

The description opens with a specific verb+resource: "Tell the Pipeworx team something is broken, missing, or needs to exist." It enumerates feedback types (bug, feature, data_gap, praise) and clearly distinguishes this tool from sibling tools like ask_pipeworx or deep_research, which are query/research 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?

Provides explicit when-to-use guidance for each feedback category and an explicit exclusion: if the tool came from a different MCP server, file it there instead. It also offers a heuristic for identifying Pipeworx tools. This is a textbook example of usage 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 it as read-only, idempotent, and non-destructive. The description adds value by disclosing caching behavior (5min-1h), data source (CF analytics-engine), and privacy (no PII), which are beyond annotations.

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

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

The description is structured with a clear opening, bulleted use cases, and additional context. It is front-loaded and each sentence adds value, though slightly verbose for a simple tool.

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

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

Given no output schema, the description adequately explains return structure (top tools, packs, call volume) and data fields (pack, tool, count). It also covers caching and privacy, making it complete for a read-only trending 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 baseline is 3. The description adds context on how window length affects output (hot vs steady-state), which enriches the parameter meaning 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 returns top tools, packs, and call volume, with a specific verb 'returns' and resource. It distinguishes itself from sibling tools like 'discover_tools' by focusing on what other AI agents are calling, not general discovery.

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?

Three explicit use cases are given: discovering hot data sources, confirming a canonical tool, and alignment checking. While it doesn't explicitly state when not to use or alternatives, the guidance is clear and actionable.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds critical behavioral details: the fill check against live CLOB depth, semantic anchor with Jaccard similarity, partition filter for placeholder slugs, and response structure. 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 thorough but somewhat lengthy; however, it is well-structured with paragraphs and bolded key terms. Every sentence adds value, but for an AI agent a slightly more condensed version could improve parseability. Still very effective.

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 (multiple modes, fill check, semantic anchor, partition filter) and lack of output schema, the description covers all relevant aspects: input behavior, response fields, and usage caveats. It is complete and leaves no critical gaps.

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

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

Schema coverage is 100%, but the description adds significant meaning: explains what event slug and topic string represent, provides examples, and clarifies how each parameter affects the scan (single-event vs. cross-event). This fully compensates and exceeds schema 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 explicitly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It clearly distinguishes three modes (no args, event, topic) and what each does, leaving no ambiguity about 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?

Provides explicit guidance on when to use each mode: no args for trending scan, event for specific market with slug, topic for cross-event scan. Also warns when not to trade (if realizable_edge_pp ≤ 0) and references polymarket_fill_risk for custom sizing, effectively differentiating from siblings.

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 fully discloses behavioral traits beyond annotations: detailed model logic, caching (1h at KV level), edge calculation net of slippage, warning on 24h move, Fed bet exclusion rationale, and diagnostic output. Annotations (readOnlyHint, idempotentHint) are consistent and enhanced.

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

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

The description is long but well-structured with sections for model families, knobs, and response structure. Every sentence provides value for a complex tool. Could be slightly more concise, but the detail is justified given the tool's sophistication.

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 (three model families, nine parameters, no output schema), the description is exceptionally complete. It explains the output format (by_segment, diagnostics, fed_candidates) and the logic behind each component, enabling the agent to understand what the tool returns and why segments might be empty.

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

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

Schema coverage is 100% and the description adds significant value beyond parameter descriptions: explains edge net of slippage, min_kelly vs min_partition_leg_kelly distinction, tradeable-edge knobs, and defaults. This helps the agent use parameters effectively.

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 scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker. It is specific about the verb 'scan' and resource 'Polymarket markets', with explicit model families.

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 targets 'what should I bet on today' and explains each model family's purpose. It does not explicitly state when not to use the tool, but the sibling names and context provide alternatives. The knob descriptions guide usage, e.g., min_liquidity for filtering thin books.

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, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: it explains snapshot creation on cache-miss, gap meaning, decay computation from daily closes (not intraday), and the 60-day TTL. No contradictions with annotations.

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

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

The description is well-structured, starting with the core purpose, then detailing response fields (tracked, expired, snapshot_dates), and ending with limits. However, it is dense and could be slightly more concise; every sentence is valuable but the length is borderline.

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 fully explains the return value structure (tracked, expired, snapshot_dates) and their components. It also covers limitations and data origins (snapshot TTL, gaps). This is complete for a telemetry tool of moderate 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 coverage is 100% with parameter descriptions. The description adds further meaning: explains 'days' as lookback (default 14, max 30) and 'window' as snapshot family (default '1wk'), plus context on snapshot writing behavior. This enriches understanding 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 provides 'edge persistence and decay telemetry' from daily snapshots, answering a specific question about how long an edge has existed and whether it is shrinking. This distinguishes it from sibling tools like 'polymarket_edges' (likely current edges) and 'polymarket_arbitrage'.

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 explains when to use this tool (to check edge persistence) and implies when not (e.g., for current edges use polymarket_edges). It also provides context on why a fresh edge differs from an older one, and includes a 'LIMITS' section that further guides usage.

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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral context: walks order book ladder, returns specific fields, and describes risks like thin_legs and forced_directional_risk. 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 lengthy but well-structured with bold headers and separate sections for single-market and basket modes. Every sentence adds necessary detail, though could be slightly more concise. Minor deduction for length.

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, so description must detail return values. It lists all returned fields for both modes, covers edge cases (thin_legs, forced_directional_risk), and explains the verdict system. Comprehensive 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%, so baseline is 3. The description enriches parameter meanings: explains size_usd interpretation for buys vs sells, basket mode size as settlement notional, and default side logic. Adds value beyond 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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and explains when to use it relative to sibling tools like polymarket_arbitrage and polymarket_edges.

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 guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale (theoretical overround uncapturable on thin books, partial fills lead to unhedged positions) and lists required parameters.

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 far beyond the readOnly/idempotent annotations, disclosing behavioral details like pairing unverified, temporal_alignment null meaning unknown rather than aligned, Kalshi fee modeling limitations, and the fact that unknown legs are never paired. It also explains that returned pairs can still carry warnings. This is exceptionally transparent and adds meaning beyond the annotation hints.

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

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

The description is long but well-organized into purpose, modes, response, safety fields, codes, flags, and caveats. It is front-loaded with the core purpose and uses formatting to separate key concepts. Some sentences are dense and repetitive (e.g., repeated emphasis on reading warnings), but every sentence adds substantive information for a tool with many safety nuances.

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

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

With no output schema, the description carries the full burden of explaining return values and safety fields. It does so comprehensively, covering top_spreads_pp, compatibility_codes, temporal_alignment, fees_note, skipped counts, and per-entry flags. An agent has enough context to invoke the tool and interpret its output correctly, including the caveat that matched pairs are not necessarily arbitrage opportunities.

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 covers 100% of parameter descriptions, so the baseline is 3. The description adds value by explaining how the three parameters interact (topic auto-fetches both sides, explicit overrides replace one side or both) and by clarifying that both modes run the same matcher. This goes beyond individual schema descriptions, though a 5 would require even more specific guidance on edge cases like partial overrides.

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

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

The description leads with a specific purpose: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes the tool from siblings like polymarket_arbitrage or polymarket_edges by emphasizing the two-venue comparison and explicitly naming the two modes. The scope is unambiguous.

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

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

The description clearly explains when to use the topic shortcuts versus explicit ticker/slug pairs, including the semantic that explicit parameters override the topic-mapped side. It provides strong context for when the tool is likely to fail ('most pre-mapped topics return compatibility_warning today') but does not explicitly name alternative tools or exclusion cases, 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?

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds context about scoping (anonymous IP, BYO key hash, or account ID) and mentions pairing with remember/forget, which provides additional behavioral insight 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 core function, no unnecessary words. Every sentence adds value: purpose, usage examples, and pairing with other tools.

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 one optional parameter, no output schema, and rich annotations, the description covers all necessary context: what the tool does, when to use it, and how it relates to sibling tools. It is complete for its 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 coverage is 100% with a single optional parameter 'key' described. The description adds that omitting the key lists all keys, but this is already evident from the schema's optional nature. No additional parameter semantics are provided beyond what the schema offers.

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: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It specifies the verb and resource, and distinguishes itself from siblings like remember and forget.

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 concrete usage scenarios: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also notes scoping and pairing with other tools, but lacks explicit 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?

Adds value beyond annotations by explaining feed behavior, mark_read side effect (marks events read for subsequent calls), and return payload. Annotations already cover safety (readOnly, idempotent, not destructive).

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

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

Four sentences, front-loaded with purpose. Every sentence provides useful information. 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?

Given no output schema, description explains return fields and alternative access URL. Covers filtering, mark_read, and polling suitability. Could mention pagination limits, but schema already provides limit parameter with default and range.

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. Description adds context for mark_read (explains side effect) and since (ISO timestamp, fired_at). No enums or nested objects, but clarity is adequate.

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?

Clearly states 'Pull fired events from your subscription feed' and specifies returned fields (source, citation_uri, payload). Distinguishes action from siblings but lacks explicit differentiation.

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 filtering options (type, since) and mark_read behavior. Mentions polling and alternative URL access. Does not explicitly compare to sibling tools or state when not to use.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses key behaviors: fan-out to multiple sources, GDELT-to-GNews fallback, USPTO API sunset soft-fail, and return structure with citation URIs. No contradictions with annotations.

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

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

The description is well-structured, front-loaded with example queries, and each sentence contributes meaningful information. It is somewhat lengthy but justified given the complexity of the multi-source fan-out.

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 absence of an output schema, the description adequately explains the return structure (changes[] grouped by source, total_changes, citation URIs). It covers main behaviors and edge cases like fallbacks and soft-fail, making it sufficiently 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?

With 100% schema description coverage, the description adds value by elaborating on 'since' parameter formats (ISO date or relative shorthand) and providing typical usage examples. It also clarifies that 'type' only supports 'company', going 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 uses multiple example queries to convey the tool's purpose: returning a change feed for a company in a recent window, fanning out to SEC EDGAR, GDELT/GNews, and USPTO. It explicitly distinguishes from the sibling tool 'entity_profile', making the purpose unmistakable.

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 guidance on when to use this tool versus 'entity_profile' (static profile vs. change feed). It also explains the fallback logic and soft-fail for USPTO. However, it does not explicitly list situations where this tool should not be used.

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 provide idempotentHint and destructiveHint; description adds key behavioral context: persistence duration (24 hours for anonymous, permanent for authenticated) and scoping by identifier.

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?

Concise and front-loaded: states purpose, then usage guidance, then behavioral details. 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?

Given the simple input schema and no output schema, the description fully covers what the tool does, when to use, and how it behaves, making it complete for an AI 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?

Schema covers both parameters with descriptions; description adds context about scoping and examples for keys, though schema already has 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 states the tool saves data for later reuse across conversations/sessions, using specific verbs and distinguishing from sibling tools like recall and forget.

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 when to use (when discovering something worth carrying forward) and provides examples, plus directs to pair with recall and forget.

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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds substantial behavioral context: it explains the cascading internal lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` listing for unresolvable identifiers, and the `figi_candidates` return for ambiguous names. This goes well beyond what annotations alone communicate and provides transparency about edge cases and failure modes.

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

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

The description is long but well-structured: it opens with the purpose and query examples, then breaks down supported types with detailed notes, and ends with enrichment/fallback behavior. Every major point has a purpose, but some details (e.g., the full list of identifier sources) could be trimmed without losing value. It is not overly verbose for the complexity it covers, and the 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?

Given the tool's complexity (multiple entity types, multiple identifier sources, ambiguity handling, degradation), the description covers everything an agent needs: input formatting, supported inputs, what it returns for each type, unresolved handling, and when to use it. There is no output schema, but the description explains return behavior adequately. No gaps remain for the agent to call it correctly.

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

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

Although the schema coverage is 100%, the description significantly enriches both parameters. For `type`, it explains the semantic difference between 'company' and 'drug' and what each resolves to. For `value`, it gives concrete examples (ticker, CIK, ISIN, names) and clarifies the exact input format, including the warning about removing security-class words for bonds. This adds substantial meaning beyond the schema's brief descriptions.

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

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

The description explicitly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It gives concrete query examples, enumerates supported types (company, drug) and even distinguishes itself from alternatives by saying 'Use FIRST whenever you have a name but need an ID.' This makes the tool's role unambiguous and clearly differentiates it from siblings like lookup_by_identifier.

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 strong usage guidance: 'Use FIRST whenever you have a name but need an ID' directly tells the agent when to choose this tool. It also specifies input formats (e.g., 'Pass the ENTITY NAME ONLY — for a bond that is the ISSUER exactly as printed'), warns against common mistakes ('trailing security-class words match nothing'), and explains that it replaces manual lookups. This is explicit when-to-use and how-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, idempotent, non-destructive behavior. Description adds value by explaining the probing mechanism (calls ai_visibility_check), ranking process, and output structure (score, confidence, signal density). No contradictions.

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

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

Three concise sentences, front-loaded with purpose. Every sentence adds value: purpose, method, use case. No unnecessary words.

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, but description fully explains return values (ranked list with score, confidence, signal density). Covers input behavior, probe mechanism, and result format. Complete for a comparison 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 has 100% description coverage, so baseline is 3. Description adds context: first entity is treated as subject, models default to workers-ai, context disambiguates. Provides usage nuance beyond 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?

Description clearly states it compares AI visibility across multiple entities using ai_visibility_check, ranks by score, and identifies most/least recognized. Distinguishes from sibling tools by focusing on AI presence auditing.

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 a clear use case example ('does Claude know about us as well as our competitors?') and context for competitive audits. Does not explicitly mention when not to use or list alternatives, but the purpose is well-defined.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description goes beyond by detailing the composite nature (fans out to two external sources), partial failure behavior with graceful degradation, and a specific timing caveat for bundlephobia (5-30s on first measurement). This adds substantial context that annotations cannot 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 dense but well-structured, front-loading the core purpose in the first sentence. It efficiently conveys usage, behavior, and output details without unnecessary words. A slight improvement would be to break into separate sentences for readability, but overall it is concise and 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?

Given there is no output schema, the description fully compensates by listing the return fields (summary block with specific keys, advisories, links, alternative versions). It also covers edge cases like partial failures and the sources_failed list. The tool is complex, but the description leaves no major gaps for an AI agent to understand what it returns and how it behaves.

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 clear descriptions for both parameters (package and version). The description merely repeats the schema content (scoped packages accepted, version defaults to latest). No additional semantic value is added beyond what the input schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly defines the tool's purpose: a composite check for 'should I add this npm package?' that combines data from deps.dev and bundlephobia. It specifies the verb ('scan') and resource ('dependency' aka npm package), and distinguishes from siblings by noting the NPM-only ecosystem constraint.

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: 'whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. Also provides clear exclusion: for other ecosystems (PyPI, Maven, etc.), use deps.dev:version directly. This gives excellent guidance on 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 safety and idempotency. Description adds specific behavioral traits: BGE-base-en embeddings + cosine over 500-char windows, 200K char cap with truncation and flagging. No contradictions.

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

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

Concise (~120 words), well-structured with key information front-loaded. Every sentence adds value 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 no output schema, describes return format accurately (top-N passages with offsets and scores). Covers input constraints, internal algorithm, and fallback behavior (truncation). Pairs with sibling tool. Complete for 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?

Schema coverage is 100%. Description reinforces limits (max 200K chars for text) and provides example queries for the query parameter, adding value beyond 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?

Clearly states 'Semantic search INSIDE a fetched record' and explains the function: given previously fetched text and a natural-language query, returns top passages with offsets and scores. Distinguishes from sibling ask_pipeworx_grounded.

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 when to use: 'Use when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter'. Also explains pairing with ask_pipeworx_grounded.

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?

Discloses key behaviors beyond annotations: auth requirements, rate limits (SMS cap 10/day), webhook auto-disable after 10 failures, and one-time secret return. 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?

Information-dense but well-structured with front-loaded purpose, examples, and delivery details. Slightly long but justified by complexity.

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?

Covers all aspects: supported types, parameter formats, delivery channel details, prerequisites, return value, and failure behaviors (webhook auto-disable). Adequate despite lack of output schema.

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

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

Adds meaningful context to all 3 parameters through examples and natural language explanations, though schema coverage is already 100%.

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

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

Clearly states 'Create a proactive monitoring subscription to a live-data event stream', specifying the action (create) and resource (subscription). Distinguishes from siblings like list_subscriptions and unsubscribe.

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 detailed when-to-use info including prerequisites (Pipeworx OAuth account) and supported types/delivery channels, but lacks explicit when-not-to-use or comparisons with alternative 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 indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint being false. The description adds behavioral context by revealing that the tool returns example questions with tool and argument shapes, and describes the categories. No contradictions.

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

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

The description is front-loaded with the core purpose and usage, but it is somewhat lengthy with many examples. While every sentence adds value, it could be slightly more concise. Still, the structure is logical and easy to follow.

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 absence of an output schema, the description thoroughly explains the return format (category-bucketed questions with tool and argument shapes). It also provides comprehensive instructions on when to use this tool, including the optional topic parameter. No 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 coverage is 100% (one parameter with description). The description adds value by clarifying the usage of the 'topic' parameter with specific examples ('finance', 'pharma', etc.) and the behavior when omitted, which is not fully captured 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 explicitly states the tool's purpose as an onboarding entry point that returns category-bucketed example questions. It uses specific verbs ('Returns category-bucketed example questions... with the exact tool + argument shape') and clearly distinguishes itself from sibling tools like 'ask_pipeworx' by being the first contact point.

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 usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains when to pass a topic argument and when to omit it, making the usage context very clear.

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 non-read-only, idempotent, and non-destructive. The description adds that the row is deactivated (not deleted) and historical events remain, which is valuable behavioral context beyond annotations.

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

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

Two sentences, front-loaded with purpose, no wasted words. Efficient and clear.

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 single parameter and no output schema, the description covers ownership, effect (deactivation), and persistence of history. Could mention success signal but not essential. Fairly 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% and the schema already describes the 'id' parameter as 'subscription id (uuid) returned by subscribe'. The description adds no further semantic detail, so 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 verb 'Cancel' and the resource 'subscription by id', distinguishing from 'subscribe' (creates) and 'list_subscriptions' (lists). It also mentions deactivation vs deletion, adding specificity.

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 ownership enforcement ('you can only cancel your own subscriptions'), which guides when to use. It does not directly contrast with sibling tools but implies this is for canceling, not listing or creating.

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 far beyond annotations by explaining the internal pipeline (SEC EDGAR fast path vs. grounded pipeline), the exact verdict types, and the crucial semantics of 'could_not_verify' vs. 'unsupported.' It discloses that 'could_not_verify' is not evidence, which is critical behavioral context that annotations cannot 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 quite long but front-loaded with trigger phrases and purpose. Every sentence adds value, covering usage, output, and error semantics. It is structured well but could have been slightly more concise without losing critical 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?

Given the tool's complexity and absence of an output schema, the description thoroughly explains all necessary aspects: when to use, how claims are routed, expected outputs, and edge-case semantics. It fully compensates for the lack of an output schema by detailing verdicts, citations, and error handling.

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 does not add parameter-specific details beyond what the schema already provides; the examples in the schema are equally informative. However, the description does add behavioral context about how different claim types are processed, which indirectly guides parameter usage.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with specific trigger phrases and a defined scope. It distinguishes itself from sibling tools by emphasizing fact-checking of user statements and the claim that it replaces multiple sequential calls.

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 whenever the agent needs to check whether something a user said is factually correct,' which provides clear usage context. It also outlines two distinct paths (company financial vs. other claims), but it does not explicitly name alternatives or list when not to use the tool, leaving some ambiguity.

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