Tomtom

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by explaining cost implications (free default, BYO key for Anthropic), return structure (score, confidence, signals, raw_response), and model default behavior, which annotations do not cover.

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

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

The description is four sentences, each informative. It front-loads the core purpose and return value, then adds model and cost details without redundancy. Every sentence earns its place.

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

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

Given 4 parameters, no output schema, and rich annotations, the description covers return format, model options, cost, and default behavior. It could mention entity length limits or rate limits, but overall it provides sufficient context for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the default model and cost trade-offs for _apiKey, and clarifies context parameter's disambiguation purpose, elevating it above baseline.

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

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

The description clearly states the tool probes LLMs for brand/business visibility and returns scores, with specific verb 'probe' and resource 'LLMs for visibility'. It distinguishes from sibling tools like ask_pipeworx (general Q&A) and deep_research (broader research) by focusing on AI marketing audits and scoring.

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 use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use the API key (for Anthropic models). However, it lacks explicit guidance on when not to use this tool or how it compares to siblings like scan_competitor_ai_presence or deep_research 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 readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context beyond annotations: it routes to a massive tool ecosystem, fills arguments automatically, returns pipeworx:// citation URIs, works on every tier, and makes a single fast call. 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 long but well-structured, with the key instruction front-loaded ('PREFER OVER WEB SEARCH') and examples listed clearly. It contains slight redundancy in repeated 'use whenever' and 'START HERE' themes, and the sibling references could be trimmed slightly, but every part adds practical 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?

For a single-parameter tool with no output schema, the description thoroughly covers the tool's role, scope, alternatives, examples, return format (structured answer with citations), and performance characteristics. It leaves no major gap for an agent deciding whether and how to use this tool, especially given rich annotations.

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

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

Schema coverage is 100% and the question parameter is described with aliases and natural language guidance. The description greatly enriches parameter meaning by providing explicit-domain lists, usage triggers ('what is', 'look up', 'find', etc.), and numerous concrete examples like 'current US unemployment rate' and 'Apple's latest 10-K', which are absent from 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 that this tool routes questions to one of 5,529 tools across verified sources and returns a structured answer with citations. It explicitly distinguishes itself from siblings by saying 'PREFER OVER WEB SEARCH' and by naming ask_pipeworx_grounded and deep_research as alternatives.

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

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

The description gives explicit when-to-use guidance: use for factual/current/historical questions, prefer over web search, and start here for most questions. It also states when to step up to ask_pipeworx_grounded (hallucination-resistant single answer) and deep_research (broad/multi-part questions), with concrete examples of triggering phrases and queries.

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

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

Beyond the readOnly/idempotent/openWorld annotations, the description reveals that candidate routing improvements are enabled live, that no candidate is currently active, that results are compared against the stable router to decide merges, and that it is a full working router rather than a fallback. This is rich behavioral context that helps the agent set expectations.

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

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

The description is four sentences, and each sentence contributes meaningful information: beta identity, current no-candidate state, usage instruction, and clarification that it is a full router. It is slightly longer than necessary but not padded or repetitive.

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 router tool with rich annotations, complete schema coverage, and no output schema, the description covers current behavior, parity with the stable version, usage context, and experimental evaluation purpose. Mentioning 'same response shape' compensates for the missing output schema, leaving no meaningful 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?

The input schema has 100% coverage: every parameter (`question`, `q`, `text`, `input`, `query`, `prompt`) is described as an alias for the question. The description adds no parameter-specific detail beyond 'same arguments' as ask_pipeworx, so the schema carries the semantic load; 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 identifies the tool as a beta universal router that is identical to ask_pipeworx in tools, arguments, and response shape, while explicitly differentiating it as the experimental edge with candidate routing improvements. This gives a specific verb ('ask') plus resource ('Pipeworx beta router') and clearly distinguishes it from the stable ask_pipeworx sibling.

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

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

It explicitly instructs: 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that it currently matches ask_pipeworx exactly. This provides clear when-to-use guidance and implicitly contrasts with the stable router, which is a strong alternative differentiator.

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 (readOnly, idempotent, openWorld), the description discloses the exact success return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and full list of refusal reasons, plus the extra LLM call cost. No annotation contradiction is present.

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 value proposition, then flows naturally into routing, return format, usage guidance, and cost. Every sentence provides unique information, and the length is appropriate for the complexity of the tool.

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

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

The description fully covers the tool's complexity: return values, refusal categories, cost trade-off, and alternative selection. Since there is no output schema, the description supplies the complete behavioral contract, making it highly complete 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?

The schema covers 100% of parameters with alias descriptions, so the baseline is 3. The description adds context that the question is routed to 5,529 tools and arguments are filled, clarifying how the question parameter drives the pipeline, which goes 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 opens with 'Hallucination-resistant answer mode for high-stakes reads' which immediately conveys a specific function and differentiates from the sibling ask_pipeworx. It explicitly describes the routing, data fetching, and grounded extraction steps, 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 explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and identifies the trade-off with 'prefer ask_pipeworx for casual lookups.' This clearly distinguishes when to use this tool versus the 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?

Extensive behavioral details beyond annotations: resolver contract, low-confidence handling, closed/dead markets, wide-spread tradeability, resolution-rule risk, parent event extraction, and fallback mechanisms. 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 very long and dense, covering many details in a single paragraph. While front-loaded with purpose, the length may overwhelm agents. Could benefit from breaking into sections or prioritizing key points.

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 thoroughly covers all major behaviors: resolver confidence, parent event, news fields, safety mechanisms, and resolution rules. Completely addresses the tool's complexity.

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

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

Schema coverage is 100% and the description adds little beyond the schema, e.g., default values for 'depth' and 'include_raw'. The schema already defines parameters sufficiently, so the description provides marginal added value.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, specifying input types (slug, URL, question text). However, it does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_arbitrage, leaving some ambiguity.

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 contexts: 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. Lacks when-not-to-use guidance or direct comparisons to alternatives, but the examples help.

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. The description adds valuable behavioral details: handles off-calendar fiscal years, sorts by primary metric, returns paired data with citation URIs, and replaces 8–15 sequential lookups. 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?

Description is dense yet concise, with front-loaded trigger phrases and efficient use of space. Every sentence serves a purpose: use cases, data details, sorting, and efficiency claim. No fluff.

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

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

Given the tool's simplicity (2 parameters, 100% schema coverage, no output schema), the description fully covers purpose, data sources, sorting, and output expectations. It provides sufficient context 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 parameters are documented. The description adds context by explaining how to use the 'values' parameter (tickers/CIKs for company, names for drug), and clarifies the sorting behavior tied to the 'type' parameter, exceeding schema alone.

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 provides side-by-side comparison of 2–5 companies or drugs, with specific use-case phrases and data type distinctions. It distinguishes itself from sequential single-pack lookups, making the purpose unambiguous.

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

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

Description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing strong when-to-use guidance. It does not explicitly mention when not to use or list alternatives, but the preference statement 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?

Goes well beyond the annotations (readOnly, openWorld, idempotent) by disclosing account requirements, paid tier for 'thorough', latency expectations, and the guarantee that gaps[] are never invented. Also explains the hop mechanics, contradiction scanning, and fetchable citation_uri 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 long but every sentence carries useful information—pricing, alternatives, scope, mechanics, output format, timing. Front-loaded with a critical account requirement and sibling alternative, though the density of detail makes it slightly heavy to parse.

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

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

With no output schema, the description fully explains the return packet: verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop fields. It also covers edge cases (gaps when topic off-catalog) and performance expectations, making it self-sufficient 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?

The schema already covers both parameters thoroughly (100% coverage), so the baseline is 3. The description adds meaningful context: the paid-plan requirement for 'thorough', the effect of depth on hop count and gap recovery, and how 'question' benefits from being broad/multi-part.

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 ('research') and resource (Pipeworx's 1455 structured data sources), clearly distinguishing it from open-web search and sibling tools. It also specifies the output (findings packet with verbatim evidence, citations, gaps) and contrasts with ask_pipeworx for single lookups.

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 (broad/multi-part questions over structured data) and when not to (single lookups, breaking/current news), naming ask_pipeworx as the alternative in both cases. Also provides account-tier guidance, including a fallback for unsigned users.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that returns top-N relevant tools with full schemas ready to call directly. No contradiction; adds useful 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?

Three sentences, front-loaded with purpose. No fluff, but could be slightly shorter. Efficiently conveys key info.

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?

Description explains return value (top-N tools with schemas), making up for missing output schema. Also gives usage timing. Complete for its complexity and rich annotations.

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

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

Schema coverage is 100%, but description adds meaning by clarifying 'query' accepts natural language, lists aliases, and mentions limit. Examples in schema help too.

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 finds tools by describing data or task, listing many example domains. It distinguishes itself from sibling tools (e.g., deep_research, entity_profile) as the discovery tool.

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

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

Explicitly says 'Call this FIRST when you have many tools and want to see the option set.' Also lists use cases (browse, search, look up, discover). Does not give when-not or alternative tools, but context is 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 read-only, open-world, idempotent, non-destructive. Description adds crucial behavioral details such as the patent source being soft-failed due to sunset, the fan-out across multiple APIs, and the return structure. Minor gap: no mention of rate limits or processing time.

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 front-loaded with examples. Every sentence adds value, but slightly long; could benefit from bullet points for the return values. Still well within acceptable conciseness for a complex 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?

No output schema, but description covers return fields (CIK, filings, fundamentals, patents, news, LEI) and mentions error conditions (patents soft-fail). References sibling resolve_entity. Lacks mention of pagination or scaling, but adequate for a single-call profile 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%, but description adds substantial context: explains that 'value' accepts ticker or CIK, not names, and that 'type' currently only supports 'company'. This goes beyond the schema 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 lists multiple example queries, specifies the tool returns a full cross-source profile of a US public company, and details the data sources and returned fields. It clearly distinguishes from sibling tools like resolve_entity.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also tells when to use resolve_entity instead if the user only has a name, and specifies valid input formats (ticker or CIK).

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 destructiveHint=true and idempotentHint=true. The description adds valuable context about why to delete (stale, done, sensitive) but does not detail further behavioral traits like permissions or side effects 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, zero wasted words, front-loaded with action and resource.

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

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

For a simple tool with one required parameter and no output schema, the description fully explains purpose, usage, and pairing with siblings.

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 parameter 'key' described as 'Memory key to delete'. The description adds no additional meaning beyond the schema. Baseline 3 for high coverage.

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

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

The description clearly states 'Delete a previously stored memory by key.' It specifies the verb (delete) and the resource (memory), and distinguishes from siblings like remember (store) and recall (retrieve).

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

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

Explicitly provides when to use the tool: when context is stale, task is done, or to clear sensitive data. Also pairs with remember and recall, offering 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?

Beyond annotations (readOnly, idempotent, non-destructive), the description details behavior: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This adds value and does not contradict annotations.

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

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

The description is brief (two sentences plus bullet list), front-loaded with the core purpose, and 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?

Given no output schema, the description clearly states the output is a single text blob ready for use. It covers the tool's process and expected result fully, making it complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add new semantic meaning beyond what the schema provides for the two parameters (url and max_links).

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, specifying the verb, resource, and context for AI crawlers. It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing 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?

The description provides explicit use cases (getting a client's site indexed, drafting own llms.txt, auditing competitors), which guides when to use it. It lacks explicit 'when not to use' guidelines, but the use cases are clear enough.

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

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

Annotations already provide read-only and idempotent hints. The description adds context about the return format (fields) and input example, which helps agents understand expected behavior 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 concise: two sentences plus an example. It is front-loaded with the core purpose and immediately provides a helpful example. Every part adds value.

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

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

For a simple geocoding tool, the description covers purpose, input, and output fields. There is no output schema, but the description lists return fields. No major gaps given the 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%, so baseline is 3. The description adds a concrete example that demonstrates parameter usage and expected format, providing extra clarity 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 it converts location queries to coordinates and lists return fields. While it distinguishes from siblings like 'reverse_geocode' implicitly by focusing on forward geocoding, it does not explicitly differentiate them.

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

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

There is no guidance on when to use this tool versus the sibling 'reverse_geocode' or other location tools. The description only explains what it does, not when it's 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 declare readOnly, idempotent, and non-destructive. Description adds no new behavioral context beyond listing fields, but does not contradict annotations.

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

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

Two sentences, front-loaded with purpose, no extraneous words. Efficient and scannable.

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

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

Description covers return fields, usage context, and is complete for a simple list tool with comprehensive annotations. No output schema needed.

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

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

Schema coverage is 100% for the single parameter. Description does not add parameter details, but schema description suffices. Baseline 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?

Description clearly states 'List the caller's active subscriptions' with specific verb and resource. Lists returned fields, distinguishing from sibling tools like subscribe/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 use cases: review before adding more or find id to cancel. Implies when to use, though doesn't explicitly 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?

Adds significant context beyond the annotations: mentions rate-limiting (5 per identifier per day), that filing without an account returns a claim_token, the token can be passed back later to read status, the team reads digests daily, and it is free and doesn't count against quota. The annotations only state readOnlyHint=false etc., and the description richly complements them 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?

The description is long but every sentence earns its place. It covers purpose, exclusions, token flow, rate limits, and roadmap impact without fluff. It uses a clear cause-effect structure with practical instructions, so the length is justified for a behavior-rich 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 the 4 optional parameters, nested context object, and no output schema, the description covers all necessary operational details: how to file, how to claim, what happens after, and constraints. It even preempts common errors like filing about other MCP servers or pasting user prompts. Complete for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining workflow semantics: how claim_token is obtained and used ('pass the pwfb_… token that filing returned, with no other arguments'), and what message should describe ('in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). It clarifies the purpose of the context object and the type enums with practical examples, adding real meaning.

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

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

The description clearly states the tool's purpose: tell the Pipeworx team something is broken, missing, or needs to exist. It distinguishes this from sibling tools by emphasizing that it is ONLY for tools served by this Pipeworx connection, and describes the specific feedback categories (bug, feature, data_gap, praise). The verb 'tell' paired with the resource 'Pipeworx feedback' 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?

Explicitly provides when to use and when not to use: use for wrong/stale data, missing tools, or praise; do NOT use for tools from a different MCP server. Offers a fallback (file it with that server instead) and disambiguates via 'Pipeworx tool names are the ones this connection lists.' This far exceeds the typical 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, and non-destructive behavior. The description adds valuable context: data derivation from CF analytics-engine, no PII, and caching behavior (5min-1h), which goes 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?

The description is concise and well-structured: a clear opening sentence, bulleted use cases, and a brief technical note. Every sentence serves a purpose 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?

The description includes the main output components (top tools, top packs, total call volume) and caching details. However, it lacks explicit output schema details (e.g., format of returned data), which would enhance completeness for a tool with 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?

The input schema fully describes the single parameter (window) with enum and semantics. The tool description reiterates the window options and adds context about interpreting shorter vs longer windows, but this adds minimal value beyond the schema (baseline 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 clearly states the tool returns top tools, top packs, and total call volume over a specified window. It distinguishes itself from siblings by focusing on aggregate trending data derived from AI agent usage, making it unique among discovery and 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?

The description lists three explicit use cases (e.g., discovering hot data sources, confirming canonical tools). While it provides clear context, it does not explicitly state when not to use this tool or mention alternatives, leaving some room for improvement.

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 readOnly, openWorld, idempotent, non-destructive. The description adds rich behavioral context: internal logic (monotonicity violations, partition checks, Jaccard similarity, placeholder filter, fill check with order book depth), response structure, and conditions for trade signals. 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 detailed and front-loaded with purpose and mode overview, but it is somewhat verbose, containing dense technical explanations that could be condensed. Nevertheless, it remains well-structured 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?

For a complex arbitrage tool with multiple modes, internal algorithms, and no output schema, the description is remarkably complete. It covers all modes, parameter behavior, algorithmic filters, response fields, fill check, and pointers to sibling tools. 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 has 100% coverage with descriptions, but the tool description adds significant value: it explains the exact usage context for each parameter ('use this if you know the specific Polymarket event'), provides concrete examples, and details the internal behavior triggered by each mode. This far exceeds mere repetition of 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 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly identifies the resource (Polymarket) and action (find arbitrage), and distinguishes between three modes (no args, event, topic) with specific behaviors. This differentiates it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description provides explicit guidance: 'Call with NO args for a trending_scan...', 'pass event for...', 'pass topic for...', and recommends 'event (recommended for a specific market)'. It also mentions when to use a sibling tool ('For custom sizing use polymarket_fill_risk'), offering clear context for selection.

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

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

The description adds significant behavioral transparency beyond annotations, detailing the three model families, edge calculation, slippage, Kelly sizing, tradeable-edge knobs, diagnostics, and caching. It aligns with annotations and provides rich context on what the tool does and how results are computed.

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 verbose with multiple paragraphs, but it is well-structured with clear sections. It front-loads the purpose and then details segments, parameters, and diagnostics. Some redundancy exists, but the structure aids understanding.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is remarkably complete. It explains the response structure, edge fields, diagnostics, caching, and even includes a note about Fed bets. It covers all necessary aspects 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 description provides minimal added value for parameters. It does offer context on tradeable-edge knobs and explains min_kelly further, but overall the schema already sufficiently documents each parameter.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for the use case 'what should I bet on today'. It distinguishes itself from siblings by focusing on data disagreement and surfacing opportunities without paging.

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

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

The description implies usage for betting opportunities but does not explicitly compare to sibling tools or state when not to use it. It provides context on the three segments but lacks direct exclusions or alternative pointers.

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 read-only, idempotent, and non-destructive behavior, which the description does not contradict. The description adds extensive behavioral details: limits on history depth (60-day TTL), decay computation from daily closes, and explains the response structure (tracked, expired, snapshot_dates). This goes well 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 well-structured with a clear opening sentence, then details the response fields, and ends with limits. It is front-loaded with the core question it answers. However, it is somewhat verbose, especially in the response enumeration, which could be more concise. Overall, it earns its length given no output schema.

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

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

With no output schema, the description fully describes the return structure, including fields like tracked[], expired[], snapshot_dates[] and their subfields (e.g., first_seen, trend, decay_pp_per_day). It also explains limits (60-day TTL) and caveats (decay from daily closes). This is complete for an AI agent to understand the tool's behavior.

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 reiterates defaults and options already in the schema (e.g., days default 14 clamp 2-30, window options 24hr|1wk|1mo). It adds minimal new semantic meaning beyond the schema, just rephrasing in context.

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: providing edge persistence and decay telemetry from daily polymarket_edges snapshots. It uses specific verbs like 'answers how long has this edge existed and is it shrinking' and distinguishes itself from siblings like polymarket_edges by focusing on time-series analysis.

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

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

The description gives clear context on when to use this tool (to differentiate between a fresh edge and an old one that persists) and provides usage context with lookback and window parameters. It doesn't explicitly name alternative tools but the differentiation is implied by the focus on historical persistence vs. current snapshots.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds beyond annotations by detailing the walks-the-ladder behavior, returned fields (verdict, slippage, thin_legs), and warnings about forced directional risk. No contradiction.

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

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

The description is thorough but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Every sentence provides value, though length could be slightly tightened. Still, it earns its space for a complex 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?

Despite no output schema, the description details all return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, thin_legs, etc.) and explains failure modes. Given tool complexity, this is remarkably 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 covers 100% of parameters with descriptions. The description adds layer-specific semantics: explains how size_usd is interpreted differently for single-market vs basket, and the default side logic for basket mode. This adds meaningful context 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 checks 'realizable-vs-theoretical edge against live CLOB order-book depth', with separate modes for single-market and basket. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly positioning itself as a prerequisite check.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the consequences of not using it (partial fills converting arb into unhedged directional position).

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?

Disclosures go well beyond annotations, detailing compatibility_warning triggers, temporal_alignment, skipped counters, and caveats about pre-mapped shortcuts. Provides comprehensive behavioral insight.

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

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

Front-loaded with purpose, but slightly verbose with detailed field explanations. Every sentence adds value, but could be more concise while maintaining clarity.

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?

Exceptionally complete for a tool with no output schema. Explains return fields, edge cases, and safety indicators in detail, covering all aspects needed for proper 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?

Adds significant meaning beyond the input schema by explaining two modes, providing examples, and describing the response structure including safety fields and temporal alignment.

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 it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. Describes two modes with examples and distinguishes from sibling tools like 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?

Explains when to use and provides scenarios where spreads may not be meaningful via compatibility_warning. Does not explicitly list alternative tools but gives sufficient context for appropriate 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 already provide readOnlyHint, idempotentHint, destructiveHint. Description adds valuable context: scoping (anonymous IP, BYO key hash, account ID) and pairing with sibling tools, which goes beyond what annotations convey.

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

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

Four sentences, no redundancy, front-loaded with primary action. Every sentence adds value: action, usage guidance, scoping, and related 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 strong annotations, the description covers all needed context: behavior, scope, and relationships with sibling tools. Complete 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 coverage is 100%. Description adds meaning by explaining the effect of omitting the key (list all keys) and contextualizing the key's purpose with examples of stored data (ticker, address, research notes).

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 what the tool does: retrieve a saved value or list all keys. Distinguishes from siblings 'remember' and 'forget' by explicit mention.

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

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

Explicitly says when to use (look up stored context) and pairs with remember/forget. No alternatives needed as it's a simple retrieval tool.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds important behavioral details: the effect of mark_read on subsequent calls, the fields returned, and that polling is appropriate. 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 efficient and well-structured, front-loading the main purpose. Every sentence adds value without extraneous verbiage. It uses natural language that is easy to parse.

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

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

Given the absence of an output schema, the description adequately covers return fields. It explains parameter behaviors and mentions an alternative access method. Minor gaps: no mention of pagination beyond the limit parameter or rate limits, but overall it is complete enough.

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

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

Schema coverage is 100% and each parameter has a schema description. The tool description adds value by explaining the interaction of mark_read with future calls and giving a concrete example for the type filter (sec_8k). This enriches the schema without redundancy.

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

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

The description clearly identifies the tool as pulling fired events from a subscription feed and lists key fields (source, citation_uri, raw payload). It is specific and unambiguous, and though it doesn't explicitly contrast with siblings, its purpose is distinct enough.

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

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

The description provides context on when to use this tool (e.g., polling works fine) and points to an alternative endpoint for scripts/dashboards. It does not explicitly list when-not-to-use, but the guidance is sufficient for typical use cases.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds significant behavioral detail: fans out to multiple sources (SEC, GDELT→GNews, USPTO), parallel call, soft-fail for USPTO, and return format.

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 single paragraph is dense but every sentence adds value. Front-loaded with relatable examples, then covers all aspects 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?

No output schema, but the description explains return structure (changes[] grouped by source, total_changes count, URIs). Also covers error handling and fallback. Comprehensive given tool 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%, but the description adds value by explaining relative time formats ('7d', '30d'), giving typical monitoring recommendation ('Use '30d' or '1m''), and clarifying that 'type' only supports 'company'.

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 provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call' and gives clear example queries. It also distinguishes from the sibling tool 'entity_profile' by specifying when to use that instead.

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 (e.g., 'What's new with X', 'latest on Y') and when not to ('Use entity_profile instead for static profile'). Also explains fallback behavior and valid input formats.

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 idempotentHint=true; description adds scoping by identifier and persistence details (24h for anonymous). No contradictions. Adds value 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?

Three sentences: purpose, use case, technical detail. Front-loaded with verb 'Save'. Every sentence adds value; no fluff.

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

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

Does not describe return value or confirmation of storage. Given no output schema, some indication of success would be helpful. Otherwise covers key aspects.

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 description adds examples of key naming conventions and value types, enhancing understanding 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?

Explicitly states 'Save data the agent will need to reuse later' with specific examples (ticker, address, preference). Distinguishes from siblings 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?

Clearly says 'Use when you discover something worth carrying forward' and mentions pairing with recall/forget. Does not explicitly state when not to use, but context is sufficient.

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

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

Beyond the readOnly/idempotent hints, it discloses source labeling, explicit unresolved-identifier behavior, graceful degradation when GLEIF/OpenFIGI are offline, and that it cascades through multiple internal lookups. It also details the exact identifier sets returned for each type.

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: opening examples, 'Use FIRST' directive, then SUPPORTED TYPES with detailed bullet-like content, and a closing note on efficiency. Each clause contributes substantive information, though it could be trimmed without losing meaning.

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

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

Given the absence of an output schema, the description thoroughly enumerates the return values (CIK, LEI, FIGI, RxCUI, etc.), source attribution, unresolved handling, and degradation behavior. It covers both entity types and the input flexibility, leaving no major operational aspect unexplained.

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 parameters with examples, and the description largely restates the input formats. It adds some output context (which IDs return per type) but that's not strictly parameter semantics; there's no new syntax or constraints 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 explicitly states the verb 'resolve' and the resource 'user-spoken NAME to canonical/official identifiers', with concrete utterance examples (ticker, CIK, LEI, RxCUI). It distinguishes itself by noting these identifiers are 'required as input' by other tools and that this should be used first, which sets it apart from sibling tools.

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

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

It gives explicit when-to-use guidance with 'Use FIRST whenever you have a name but need an ID.' It enumerates supported entity types and input formats, but does not name alternative tools to use instead for other cases, so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the description's addition of return fields and an example provides some context but does not deeply disclose behavior 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?

Two concise sentences with an example, no wasted words. Structure is front-loaded with 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 the simple tool (lat/lon input, address output), the description covers purpose, parameters, example, and return fields. With strong annotations, no gaps remain.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description reiterates lat, lon, and the optional API key with an example, adding marginal value over 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 converts coordinates to a human-readable street address and lists the returned fields. It is specific but does not explicitly differentiate from the sibling 'geocode' tool.

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

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

The description implies usage for reverse geocoding but gives no explicit guidance on when to use this tool instead of alternatives like 'geocode' or other tools.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that it uses live traffic and reports traffic delay, providing behavioral context beyond annotations. 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 three sentences plus an example, front-loading key information (traffic-aware, returns distance/time). No redundant 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 tool's complexity, schema covers all parameters, and annotations provide safety profile. Description explains return values (distance, travel time, traffic delay) sufficiently. No output schema needed.

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

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

Schema descriptions cover all 6 parameters (100% coverage). Description adds an example and mentions travel modes, but does not significantly enhance parameter meaning beyond the schema. 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 provides traffic-aware routing/directions, calculates best route, returns distance and travel time with live traffic. It distinguishes from sibling tools like geocode (address to coordinates) and search_poi (POI search) by focusing on route calculation between two points.

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 specifies when to use (for live traffic ETAs, delays) and mentions supported travel modes. However, it does not explicitly exclude alternatives among siblings, but since no other routing sibling exists, this is adequate.

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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds value by revealing that the tool internally calls ai_visibility_check for each entity and returns a ranked list with score, confidence, and 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?

The description is two sentences long, front-loaded with core functionality, and every sentence adds value. No redundant 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 parameter count (4) and schema coverage (100%), the description adequately covers return values (ranked list with metrics), use case context, and parameter semantics. No output schema exists, but the description provides sufficient clarity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining that the first entity is treated as the 'subject' for narrative purposes and clarifying optional model parameters and the need for an API key when using 'anthropic'.

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 compares AI visibility across multiple entities, probes each with ai_visibility_check, and returns a ranked list. It uses specific verbs like 'Compare' and 'Probes' and distinguishes from sibling tools like ai_visibility_check by emphasizing multi-entity comparison.

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

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

The description provides clear context for when to use the tool: 'competitive AI-marketing audits' with the example question. It does not explicitly state when not to use or list alternatives, but the context is clear and sufficient for agent decision-making.

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 readOnly=true, idempotent=true, non-destructive. The description significantly adds behavioral context: composite fan-out across two services (deps.dev and bundlephobia), potential 5-30s delay for new version measurements, graceful degradation with sources_failed list, and return structure (summary, advisories, links, alternatives). 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 comprehensive but somewhat verbose; however every sentence adds value. It front-loads the main purpose with a bold claim ('Composite check in ONE call'). The structure flows logically: purpose, use case, returns, limitations, failure handling. Could be slightly tighter, but not overly bloated.

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

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

Despite no output schema, the description enumerates the return fields (is_latest, license, published_at, advisory_count, bundle sizes, dependency_count, ESM/tree-shake support, per-advisory detail, links, alternative versions). It also explains partial failure and sources_failed. This provides sufficient context for an AI agent to understand what the tool returns and how to handle edge cases.

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

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

Input schema describes both parameters with 100% coverage. The description adds value by clarifying that package is an npm name (with scoped package example), and that version defaults to latest. While schema already states this, the description reinforces and provides context about the default behavior and scoped packages.

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 composite purpose: checking npm package safety, popularity, size, and cost in one call. It uses specific verbs like 'scan', 'fans out', 'returns', and lists concrete aspects (license, advisories, bundle size). It distinguishes from sibling tools by focusing on npm dependency evaluation, a unique niche among the listed siblings.

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

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

The description provides clear usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also notes ecosystem limitations (NPM only in v1) and provides fallback alternatives (deps.dev:version for other ecosystems). Partial failure behavior is explained, guiding expected behavior.

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, covering safety and idempotency. The description adds return field details but no additional behavioral context (e.g., rate limits, data freshness). With annotations present, the description contributes some value but not significant beyond structured fields.

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

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

The description is a single sentence front-loaded with purpose, followed by parameters and return fields, plus a compact example. Every word is useful, no redundancy, and it is appropriately sized 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 no output schema, the description lists all key return fields (name, category, address, coordinates, phone, url, distance) and provides an explicit example. All six parameters are covered in schema and description, making the tool's functionality complete 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 coverage is 100% with each parameter described. The description reinforces parameter usage via example and mentions 'by name or category' and 'near a lat/lon center', but does not add novel semantic information beyond the schema. 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 'Search for points of interest (POIs) ... by name or category', specifying the verb, resource, and scope. It lists return fields and provides an example, making the tool's purpose unambiguous and distinct from sibling tools like geocode or route.

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

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

The description implies usage for POI searches but does not explicitly state when not to use this tool or mention alternatives. No exclusions or comparison to siblings like search_within or geocode are provided, limiting guidance for agent decision-making.

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, destructiveHint. The description adds valuable behavioral context: embedding model (BGE-base-en), similarity metric (cosine), windowing (500-char overlapping), character cap (200K), truncation with flagging, and output details (passages, offsets, similarity scores). 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 concise, around 5 sentences, with each sentence adding critical information. It is front-loaded with the core function, followed by usage, pairing, and technical 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?

Considering there is no output schema, the description adequately explains the return values (passages, offsets, similarity scores). It also covers technical details like embedding model, windowing, and truncation. For a tool of this complexity, the description is thorough and 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% with clear descriptions for all three parameters. The description adds value beyond schema by providing example queries, explaining the truncation behavior for 'text', and noting the default 'limit' value. This enhances understanding but the schema already handles basic semantics.

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

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

The description clearly states the tool performs semantic search inside a fetched record, returning relevant passages with character offsets and similarity scores. It uses specific verbs ('search') and resource ('inside a fetched record'), and distinguishes from sibling tools like ask_pipeworx_grounded by explaining the pairing 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 explicitly states when to use the tool: when the record is too large for the prompt. It also suggests pairing with ask_pipeworx_grounded for grounding over passages. This provides clear context and alternatives, with no ambiguity.

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

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

Annotations indicate readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context beyond annotations: requires OAuth, creates a persistent subscription, returns an ID, and details channel constraints (SMS cap, webhook secret one-time delivery). It does not contradict annotations. No hidden side effects are omitted, though idempotency implications or error conditions could be mentioned.

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

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

The description is relatively long but front-loaded with purpose and requirements. It is structured into sections (requirements, types, delivery) and every sentence adds necessary detail. A slight trimming of examples could improve conciseness without losing value.

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

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

Given the complexity (3 parameters, nested objects, no output schema), the description covers purpose, auth, types, delivery options, and constraints. It mentions the return value (subscription id) but does not describe the full response format or error handling. The description is largely complete for effectively using the tool.

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

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

Schema coverage is 100%, but the description adds significant value by providing concrete examples for each type and delivery channel, including nested object structures. It explains the meaning and constraints (e.g., enum values, required fields in params) beyond the schema's minimal 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 clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It specifies the verb (create), resource (subscription), and outcome (returns ID). The tool name subscribe and title match, and it effectively distinguishes from sibling tools 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?

The description explicitly states prerequisites ('Requires a Pipeworx OAuth account') and lists supported types with examples. It provides delivery channel constraints (SMS verifications and cap, webhook signature details). However, it does not explicitly contrast with sibling tools (e.g., when to use subscribe vs. list_subscriptions or recent_alerts), which would elevate clarity.

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. Description adds behavioral detail: no arguments for full spread, optional topic filter, returns exact tool+argument shape. No contradictions. Could mention if results are paginated, but not needed given simplicity.

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?

Description is front-loaded with aliases and uses one dense paragraph with clear structure. Every sentence adds value. Could be slightly more structured (e.g., bullet points) but remains effective and concise.

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

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

Given simple input schema, no output schema, and one optional param, the description is complete. It explains return type (category-bucketed examples with tool+argument shapes) and usage scenarios. 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 100% with one optional parameter. Description adds examples of topic values ('finance', 'pharma', 'betting') and explains behavior when omitted. This enhances understanding beyond the schema's enum-like description.

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

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

Description clearly states it returns category-bucketed example questions and serves as an onboarding entry point. The title and aliases ('What can I ask Pipeworx?') reinforce purpose, and it distinguishes from sibling tools like ask_pipeworx and discover_tools by specifying it provides example questions with tool+argument shapes.

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 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also lists alternatives (ask_pipeworx, entity_profile, etc.) and explains when to use the optional topic parameter.

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 significant value beyond annotations by explaining the deactivation behavior ('row is deactivated, not deleted') and the impact on historical data via 'recent_alerts'. This aligns with annotations (destructiveHint=false) and provides concrete behavioral details.

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

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

The description is extremely concise, using two sentences to convey purpose, constraints, and behavioral nuance. No redundant or unnecessary information is present.

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

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

For a simple tool with one parameter and clear annotations, the description is complete. It covers purpose, ownership, mutation behavior, and the fate of historical data. No output schema exists, so the lack of return value description is acceptable.

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

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

Schema coverage is 100% for the single parameter 'id', and the description does not add new meaning beyond the schema's own description. Therefore, the description meets the baseline but does not provide additional semantic value.

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

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

The description clearly states the action ('Cancel a subscription') and the resource ('by id'), and distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by specifying the deactivation behavior. The title aligns well.

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 context for when to use the tool (to cancel a subscription) and includes a key constraint (ownership enforcement). However, it does not explicitly list alternatives or 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses critical behavioral details: the verdict vocabulary, the crucial could_not_verify vs. unsupported distinction, and the error object format. It also explains the SEC EDGAR + XBRL fast path and grounded pipeline routing. This adds substantial context beyond the safe-read annotation.

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. Trigger phrases at the start front-load utility, and caveats about could_not_verify are essential for correct call handling. Every sentence contributes value; the only minor inefficiency is the repeated trigger phrase list, but it aids recognition.

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

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

This is a complex tool with no output schema, so the description carries the full burden. It covers return values, verdict semantics, error handling, evidence citations, and routing logic. It also explains the tool's relationship to other tools by noting it replaces 4–6 sequential calls, making the description complete for an agent to invoke and interpret results.

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

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

The schema already documents both parameters fully (100% coverage). The description adds meaning by explaining that tolerance_pct overrides the tolerance implied by claim wording, is capped at 5, and is useful for hallucination detection. This goes beyond the schema's basic type/description.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It distinguishes itself from sibling tools by explicitly defining scope (company-financial vs. any other factual claim) and positioning itself as a single-call replacement for multi-step verification. The verb 'verify' and resource 'claims' are specific and 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 provides clear usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates the two internal routing paths based on claim type. However, it does not explicitly state when NOT to use the tool or name alternative sibling tools, though the phrase 'Replaces 4–6 sequential calls' implies preference over manual pipelines.

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