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 behavior, so the description only needs to add context rather than carry the full burden. It does add useful behavioral detail by explaining that the tool routes to external tools, fills arguments, and returns structured answers with citation URIs. It does not describe failure modes or rate limits, but those are not essential given the annotation profile.

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 substantially longer than needed and contains noticeable redundancy: 'START HERE' appears twice, 'even if web search could also answer it' appears twice, and 'Use whenever the user asks...' is repeated. There is also a garbled fragment ('For a polynomial thing?') that hurts clarity and trust in the definition.

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 high-complexity routing tool with no output schema, the description is largely complete: it covers the input type, example queries, answer format with citations, and the main sibling alternatives. It could be improved by explaining more about the shape of the structured answer or how to handle ambiguous questions, but the core invocation context is sufficiently covered.

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 all parameters at 100% coverage, including the question parameter and its aliases, so the baseline is 3. The description adds extra semantic signal by providing concrete example questions and trigger phrases like 'what is', 'look up', 'find', and 'current', which help the agent understand what kind of input is expected.

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

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

The description clearly identifies the tool as a question router that picks from 5,798 tools across 1,517 verified sources, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It also distinguishes itself from web search and sibling tools by naming what it is preferred for, so an agent can identify it without opening schemas.

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

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

The description gives explicit when-to-use guidance: prefer over web search, use for factual questions about real-world data, and start here for most questions. It also names specific alternatives for different cases, including deep_research for broad multi-part questions, remember/recall for private or closed-context answers, ask_pipeworx_grounded for verifiable grounded answers, and route for tool routing decisions.

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 readOnlyHint, openWorldHint, and idempotentHint annotations, the description discloses time-varying behavior: candidate routing improvements are enabled live whenever under test, and no candidate is active right now, so the tool currently matches ask_pipeworx exactly. It also explicitly says it falls back to nothing, which prevents the common beta-tool misconception. No contradiction with the annotations exists.

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

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

The description is well structured and front-loaded with the most important identity statement, 'Beta version of ask_pipeworx.' It contains some operational detail, such as the tool count and the retirement date, which is useful for transparency but slightly exceeds what is strictly needed for invocation. Overall it is compact and every sentence contributes.

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

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

The description is complete for a router tool: it explains what the tool is, how to use it, what its current behavior is, and that its response shape matches ask_pipeworx. The input schema covers all parameters, the annotations cover safety, and the description covers the beta-specific nuances an agent would need to call it correctly.

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

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

Schema description coverage is 100%, and the schema already documents question plus all five aliases (q, text, input, query, prompt). The description adds only the high-level statement that arguments are the same as ask_pipeworx, but no field-level semantic detail beyond the schema. This is the appropriate baseline for a fully documented 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 defines the tool as the beta version of ask_pipeworx, an identical universal router with the same tool set, arguments, and response shape. It explicitly contrasts this with the stable router and says to use it exactly like ask_pipeworx, which differentiates it from the main sibling. It is specific about the resource and what the tool does, even if it does not discuss ask_pipeworx_grounded.

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

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

The description gives explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that results are compared against the stable router, which implies when the stable route is preferable. It further prevents misuse by stating there is no fallback and that this is a fully working router.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses refusal behavior, exact refusal reasons, the evidence requirement, the return shape, and the extra cost. It clearly explains that answers are strictly constrained to the tool result, which helps an agent trust and anticipate failures.

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?

Dense but every sentence earns its place: purpose, routing behavior, return/refusal contract, use cases, and cost trade-off are all covered without repetition. The critical grounding constraint is front-loaded in the first sentence.

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

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

For a tool with complex refusal semantics and no output schema, the description is unusually complete: it specifies both success and failure shapes, refusal reasons, the strict verbatim-evidence behavior, and the cost comparison to its sibling. Nothing an agent needs to decide when to call it or interpret its result is missing.

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

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

Schema coverage is 100% and the schema already documents the question parameter and its aliases. The description adds meaningful context by explaining that the question is routed across thousands of tools and used to fill arguments, clarifying how the parameter is interpreted beyond being a plain string.

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

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

The description states a specific, distinctive function: a hallucination-resistant, grounded answer mode that extracts answers only from tool results. It explicitly contrasts itself with ask_pipeworx and names the routing behavior, making sibling differentiation clear.

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

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

Gives explicit when-to-use guidance: whenever an answer will be quoted, cited, or acted on and facts must not be invented, with concrete domains like financial verdicts and legal claims. It also states the trade-off (one extra LLM call) and explicitly says to prefer ask_pipeworx for casual lookups.

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?

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial context beyond them: account/pricing prerequisites, explicit 'never invented' claims about gaps[], the guarantee that citation URIs are only present when fetchable, semantic excerpting behavior, contradictions[] scanning, and latency expectations. Nothing contradicts 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 long but every sentence carries distinct information — prerequisites, fallback, scope, methodology, output packet, gaps, alternatives, depth behavior, citation guarantees, latency. It is well front-loaded with the account warning and sibling fallback. It loses a point only for being a dense wall of text with some depth-related details repeated from the schema.

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

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

For a tool with two parameters, rich annotations, many siblings, and no output schema, the description covers everything an agent needs to invoke it correctly: auth/plan requirements, the findings-packet return shape, the gaps[] and contradictions[] fields, citation fetchability, and estimated latency. The absence of an output schema is compensated for by the explicit description of what gets returned.

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 earns an extra point by adding operational meaning to the depth parameter (what gap-recovery and lead-chasing hops do in 'standard' vs 'thorough') and tying depth choices to time expectations (15-60s, up to ~90s). The question parameter additionally receives guidance that 'Broad/multi-part is fine.'

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

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

The description names a specific verb-resource pair — 'grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources ... in ONE call' — and explicitly differentiates it from open-web search and from ask_pipeworx. An agent can tell exactly what this tool does and what it is not without opening the schema.

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

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

The description states explicit when-to-use ('Best for broad/multi-part questions over structured data'), gives a concrete example, and names exclusions: 'For a single lookup use ask_pipeworx instead' and 'If you are not signed in, use ask_pipeworx instead — it works on every tier.' The routing guidance is direct and actionable.

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

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

Annotations already declare 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 establish read-only, open-world, idempotent, non-destructive behavior. The description adds valuable behavioral context beyond that: the tool fans out in parallel, reports sources_used/sources_failed, treats empty sections as real 'no data' rather than bugs, and returns resolved:false for private companies. It also explains the fallback chain from GDELT to GNews and name resolution via SEC EDGAR.

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 and front-loaded with examples and the key 'ALWAYS PREFER' guidance. It contains a lot of detail about return sections and input forms, which is useful, but some content near the end (the type interchangeability note) repeats schema information. Overall it earns its length, though it is slightly over-stuffed.

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

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

There is no output schema, so the description carries the full burden of explaining return values, and it does so thoroughly: it lists every returned section, mentions resolved_from/resolved_to, source success/failure reporting, and edge cases like private companies. An agent has enough context to call the tool correctly and interpret the result without guessing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it gives concrete examples ('AAPL', '0000320193', 'Moderna'), explains that 'company' and 'ticker' are interchangeable, and clarifies that a company name is resolved via SEC EDGAR. This enriches the parameter understanding without contradicting 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 states a precise purpose: build a full cross-source profile of a US public company in one parallel call, with concrete invocation examples ('Tell me about X', 'brief me on Tesla'). It distinguishes itself from single-source lookups by explicitly saying it fans out across SEC, XBRL, USPTO, USAspending, FDA, DOL, news, and GLEIF sources.

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 is explicit about when to use this tool: whenever the user asks for a holistic view of a company, and it instructs the agent to ALWAYS PREFER it over chaining single-pack SEC/XBRL/news lookups. It also specifies accepted input forms (ticker, CIK, company name) and clarifies the behavior for private companies, which is strong usage guidance.

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

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

Annotations already 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?

With annotations already declaring readOnly and idempotent hints, the description goes far beyond them: it explains the meaning of compatibility_codes, that unknown metric_type/match_subtype legs are never paired, that temporal_alignment null does not mean aligned, and that spreads are gross because Kalshi fees are not modeled. This is exemplary disclosure of limitations and edge-case behavior.

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

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

The description is a dense single block of text with many parentheticals, long sentences, and some repetition (e.g., the identical-matcher point is made twice). Every sentence does add information, but the lack of structure (no lists or headings) makes it harder to parse than it could be. It is comprehensive but not 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 the tool's complexity (two modes, many safety codes, flags, skipped counters) and the absence of an output schema, the description carries a heavy burden and fulfills it: it explains response fields, warning codes, the fee caveat, and the meaning of temporal fields. Nothing essential for invoking the tool correctly appears to be missing.

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

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

Though the schema already covers all three parameters (100% coverage), the description adds substantial meaning: it enumerates the topic shortcuts, explains that explicit parameters override topic-mapped sides, and clarifies that both modes run the identical token-overlap matcher. This goes well beyond the baseline 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 opens with a specific verb-resource statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It then details two modes and the response contents. The tool is clearly differentiated from siblings like polymarket_arbitrage by explicitly naming the two venues and the concept of a cross-venue spread.

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 the topic-mode shortcuts versus explicit ticker/slug pairings, and warns that pre-mapped topics often return compatibility_warning and are not necessarily tradeable. It stops short of naming alternative sibling tools or stating explicit when-not-to-use conditions, but the internal routing guidance is strong.

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

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

Annotations already 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?

The description is highly transparent about internal behavior: it details the cascading lookup endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, and the possibility of returning `figi_candidates` when multiple matches exist. It also discloses the return format for drugs (RxCUI, ingredient, brand) and the source mappings, going well beyond the read-only/idempotent 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 densely packed with details, including numerous parenthetical explanations and edge cases. While front-loaded with purpose and usage, the verbosity might strain readability. However, the complexity of the tool justifies the length, and the structure (purpose, usage, supported types, parameters) is logical.

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 does a good job explaining what the tool returns: it mentions returned identifiers for company (CIK, ticker, LEI, FIGI) and drug (RxCUI, ingredient, brand), as well as `figi_candidates` and `unresolved` fields. It also covers error behavior (graceful degradation) and internal cascade, but it does not fully enumerate all possible output fields or response structures, which is a minor gap.

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

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

Both parameters are thoroughly explained: `type` has its enum values and meanings, and `value` is described with concrete examples for each type, including warnings about how to format bond issuer names to avoid matching failures. The description also notes specific valid input formats (ticker, CIK, ISIN, brand/generic name), covering all schema properties with high precision.

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

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

The description clearly states that the tool resolves a user-spoken name to canonical identifiers, with specific examples of queries and supported entity types. It distinguishes between company and drug entities and explains how it replaces multiple manual 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?

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' giving direct usage guidance. It also explains when to use it over alternatives (replacing 2-3 manual lookups) and mentions graceful degradation, providing clear context for when to invoke the tool.

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

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

Annotations already declare readOnlyHint, 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.