Coordinates

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds context on model selection, API key handling (BYO key, direct payment), and return structure. No contradictions. The description enhances transparency 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?

Description is compact (4 sentences) with front-loaded main purpose. Each sentence adds essential information: action, model options, return format, use cases. No wasted 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?

For a tool with no output schema, description adequately covers return values (per-model {score, confidence, signals, raw_response} + combined view). It also explains the default model and optional Anthropic integration. Missing details like pagination or error handling, but overall sufficient for a probing tool with safe 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%, so parameters are already documented. Description adds value by explaining default model behavior, how _apiKey is used (passed straight through), and how context helps disambiguate. This provides semantic understanding beyond the schema.

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

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

Description clearly states the tool probes LLMs and scores visibility for entities. It specifies verb ('probe'), resource ('LLMs'), and outcome ('score visibility 0-100'). The output format is described, distinguishing it from sibling tools like deep_research or scan_competitor_ai_presence.

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 provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use the optional Anthropic model. However, it does not mention when not to use or compare to alternatives, leaving some 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 already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context beyond annotations: routing behavior, argument filling, stable citation URIs, a shared 95k call quota, and the absence of a code execution tool. However, the trailing 'STUB.' is an unexplained artifact that prevents a perfect score.

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

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

The description is front-loaded with its most important guidance ('PREFER OVER WEB SEARCH') and includes many useful details. However, it is quite long, packs numerous alternative tool names into dense paragraph flow, and ends with an unexplained 'STUB.' marker. Every sentence mostly earns its place, but the structure is not as clean as it could be.

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

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

Given there is no output schema, the description covers the return value well: 'structured answer with stable pipeworx:// citation URIs'. It also provides domains, examples, quota limits, and sibling-tool routes, which makes the tool actionable. A minor gap is that failure/error behavior and the meaning of the 'STUB.' marker are not explained.

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

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

The schema already covers all six parameters at 100% — they are all aliases for the same free-text question. The description adds substantial meaning beyond the schema by explaining what kinds of questions to ask, providing rich examples, and listing trigger phrases. It does not repeat schema details but instead clarifies the intended input 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 that ask_pipeworx routes questions to one of 5,798 tools across 1,517 verified sources and returns structured answers with pipeworx:// citation URIs. It names specific data domains and gives concrete example queries, which distinguish it from vague 'ask a question' tools. It also explicitly contrasts itself with sibling tools like deep_research and 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 when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and trigger phrases like 'what is', 'look up', 'find', and 'get the latest'. It also names alternatives for specific cases: ask_pipeworx_grounded for citation follow-ups, deep_research for multi-angle research, bet_research/polymarket_* for breaking news, and discover_tools for capabilities. This is unusually strong routing 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?

Beyond the readOnly, openWorld, and idempotent annotations, the description discloses that candidate routing improvements are enabled live, that no candidate is currently active, and that this is a fully working router with no fallback. This is substantive context about the experimental state and current behavior, and it does not contradict the annotations.

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

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

The description is front-loaded with the beta identity and current state, then gives usage and fallback clarity. It is slightly verbose and the phrase 'Falls back to nothing' is awkward, but every part contributes essential selection and invocation context.

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

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

For a read-only, idempotent tool with an alias-heavy schema, the description covers purpose, current state, usage, and relationship to the stable router. It defers response shape to 'same response shape' as ask_pipeworx, which is acceptable because that sibling is listed, but it is not fully self-contained without referencing that sibling.

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

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

Schema description coverage is 100%, so all six parameters and their alias relationship to 'question' are already documented. The description adds only that arguments are identical to ask_pipeworx, which reinforces but does not meaningfully extend the schema, so the baseline 3 applies.

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

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

States clearly that this is the beta variant of ask_pipeworx: an identical universal router with the same 5,798 tools, same arguments, and same response shape. It also distinguishes itself from the stable ask_pipeworx by its experimental routing status, so an agent can tell it apart immediately.

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 it exactly like ask_pipeworx when you want the newest routing.' It also notes the current state (no candidate active) and how results are compared against the stable router. However, it does not explicitly state when to avoid this beta or when to prefer ask_pipeworx_grounded, so exclusions remain implicit.

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

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

The description goes well beyond the annotations by disclosing the exact success shape, refusal reasons, evidence quoting behavior, and the constraint that the answer is extracted only from the tool result. It also notes the extra LLM call cost. Nothing contradicts the readOnlyHint, openWorldHint, idempotentHint, or destructiveHint 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 longer than average but every sentence earns its place: it conveys purpose, usage context, routing behavior, return structure, refusal conditions, and cost tradeoff. It is front-loaded with the key differentiator ('Hallucination-resistant answer mode') and structured so an agent can quickly extract the decision-relevant 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?

Despite no output schema, the description fully specifies the return shape and all refusal reason values. It also covers when to use the tool, when not to, how it differs from ask_pipeworx, and its safety profile. For a tool of this complexity, the description gives an agent everything needed to call it correctly and interpret the result.

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

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

Schema description coverage is 100%, with the schema thoroughly documenting the question parameter and its aliases. The tool description does not need to restate parameter details, so baseline 3 is appropriate. It adds no special parameter semantics beyond what the schema already provides.

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

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

The description clearly identifies this as a grounded, hallucination-resistant answer mode that routes like ask_pipeworx, fetches data, and extracts answers only from the tool result. It distinguishes itself from siblings by emphasizing evidence-grounded answers and explicit refusal behavior, so an agent knows exactly what this tool does and how it differs.

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 this tool: when answers will be quoted, cited, or acted on, and when the agent must not invent facts, with concrete examples. It also gives an exclusion and alternative: prefer ask_pipeworx for casual lookups because this mode costs an extra LLM call.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. The description adds extensive behavioral details: fan-out logic per classifier, response shapes, resolver contract, parent event extraction, news fields with fallback info, safety on low-confidence matches, closed market handling, liquidity warnings, and cancellation rule parsing. 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 lengthy but well-structured with examples, bullet points, and sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). The first sentence immediately states purpose. Some redundancy could be trimmed, but the complexity justifies the length.

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

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

Despite no output schema, the description thoroughly explains return values, response shapes, and edge cases (low confidence, closed markets, wide spreads, cancellation rules). Covers all aspects a user needs for effective tool usage.

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%; description adds context beyond schema: explains input resolution (slug, URL, text), depth options (quick vs thorough), and include_raw purpose and trade-offs. Enhances understanding of all three parameters.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types and output components, distinguishing it from sibling tools like polymarket_edges or validate_claim.

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

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

Explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Also warns to inspect resolver confidence before trusting analysis, and mentions the tool is not for edge tracking across markets (handled by polymarket_edges).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds the behavioral detail that the tool returns SW/NE corners of the bounding box. 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?

Single sentence that front-loads the purpose and includes key parameter details. No redundant words, highly efficient.

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

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

Annotations are comprehensive, and the tool's output is implied by 'SW/NE corners'. The description is sufficient for a simple geometric computation tool, though it could explicitly state the return format.

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 4 parameters with 50% description coverage (unit and radius have descriptions). The description adds context by clarifying the output format (SW/NE corners) and the default unit, complementing the schema. However, it does not add new semantic constraints beyond what the schema provides.

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

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

Description clearly states the tool computes a bounding box (SW/NE corners) from a center point and radius. It distinguishes from sibling spatial tools like centroid or midpoint by specifying the output geometry and parameters.

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 provides the default unit (km) and alternative (mi), but no explicit guidance on when to use bounding_box vs other sibling tools. Usage context is implied through the description of the tool's function, but no exclusions or alternative recommendations are given.

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

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

Description matches annotations (readOnly, idempotent). No additional behavioral details beyond what annotations provide, but 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?

Two sentences, no wasted words. Purpose and parameter clearly stated in minimal space.

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

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

No output schema, but tool is simple. Description could mention return format (single {lat,lon}) for completeness. Adequate but not thorough.

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 already fully describes 'points' parameter (100% coverage). Description only repeats schema info, adding no new 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 computes the average (spherical) center of lat/lon points. It distinguishes from sibling 'midpoint' by specifying spherical calculation.

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?

No guidance on when to use this tool vs alternatives like 'midpoint'. Lacks explicit when-to-use or when-not-to-use context.

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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds critical context: for type='company' it pulls latest 10-K financials from SEC EDGAR/XBRL, handles off-calendar fiscal years correctly; for type='drug' it pulls FAERS adverse-event counts, FDA approval counts, and active trial counts. It also explains sorting by primary metric and return of citation URIs. 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 a single paragraph that effectively front-loads examples and purpose. Every sentence adds value, but the structure could be slightly improved with bullet points for readability. Still, it is concise for the complexity.

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

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

Given the tool's complexity (two entity types, multiple data sources), the description covers main behaviors comprehensively: data sources, sorting, return of paired data and citation URIs. It compensates for the lack of an output schema by explaining the result characteristics.

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 has 2 parameters (type, values) with 100% schema coverage. The description adds meaning beyond the enum and array descriptions: explains what data is pulled for each type (e.g., revenue, net income, cash, debt for company; FAERS counts, FDA approvals, trials for drug) and specifies value formats (tickers/CIKs for company, drug names).

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, using action verbs like 'compare', 'rank', and 'head to head'. It distinguishes itself from sibling tools such as entity_profile (single entity) and deep_research (extensive research).

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

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

The description explicitly instructs to prefer this tool over sequential single-pack lookups when comparing entities, and provides examples like 'which is bigger', 'rank these companies'. It sets clear expectations for when to use.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive, and the description does not contradict them. It adds substantial behavioral context beyond the annotations: account and paid-plan requirements, parallel decomposition across 5,798 tools, explicit gap reporting with no invented findings, contradictions[] behavior, citation resolvability, semantic excerpting, and expected latency. This is rich, accurate transparency.

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

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

Although longer than typical descriptions, every sentence earns its place: auth and alternative routing are front-loaded, followed by core behavior, return format, depth semantics, and latency expectations. The structure flows logically from prerequisites to function to output details. Nothing feels redundant or decorative.

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 research tool with no output schema, the description thoroughly covers what an agent needs: when to use it, auth constraints, fallback alternatives, depth tradeoffs, response contents, citation behavior, gap handling, and runtime expectations. It is complete enough that an agent can select and invoke the tool correctly without additional documentation.

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 coverage is 100%, so the parameters are already well documented. The description adds meaningful context beyond the schema by clarifying the paid-plan requirement for depth:'thorough' and by reinforcing that question supports broad natural-language decomposition. It does not need to restate schema details, and it adds enough extra semantics to justify a score above the 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 opens with a clear, specific function: grounded multi-source research across Pipeworx's 1,517 structured data sources in one call, explicitly distinguishing itself from open-web search. It also differentiates from sibling ask_pipeworx by naming the alternative and the condition for choosing it. The verb, resource, and scope are all concrete and immediately actionable.

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: broad/multi-part questions over structured data, and explicitly says to use ask_pipeworx for a single lookup or when not signed in. It also notes that depth:'thorough' requires a paid plan, adding a practical selection constraint. This fully equips an agent to route between deep_research and its siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by noting that results include full input schemas with curated examples and are ready to call directly, which is not covered by annotations.

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

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

The description is somewhat lengthy but every sentence adds value. It front-loads the core purpose and usage guidance. Could be slightly more concise, but no waste.

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 explains the return value (top-N tools with names, descriptions, and full schemas). Parameter count is reasonable with aliases correctly handled. Complete and self-sufficient.

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 enhances parameter understanding by listing accepted aliases for 'query' and providing example queries. It clarifies that 'limit' defaults to 20 and maxes at 50, adding 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's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, FDA drugs, etc.) and distinguishes itself from siblings, none of which are discovery 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?

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on when to use versus alternative approaches.

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

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

The description goes far beyond the annotations, explaining the parallel fan-out across many sources, soft-fail behavior for USPTO, why empty FDA results are expected, the meaning of sources_used/sources_failed, and private-company handling with resolved:false. This gives the agent crucial behavioral context that annotations cannot convey.

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

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

The description is long but the tool is complex and lacks an output schema, so the extra detail is largely justified. It front-loads the core purpose and preference rule before enumerating return sections, though a structured bullet format would improve scannability.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: every returning section is named, failure modes are explained, and expected empty results are distinguished from bugs. Nothing an agent needs to correctly invoke and interpret the tool 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%, but the description adds meaningful semantics: type accepts company/ticker interchangeably, value can be a ticker, zero-padded CIK, or company name, and names resolve via SEC EDGAR. This clarifies usage beyond the schema's literal field 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 the tool's purpose: a full cross-source profile of a US public company in one parallel call. It gives multiple concrete user-phrase triggers and explicitly differentiates itself from chaining individual SEC/XBRL/news lookups.

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

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

It explicitly tells the agent to ALWAYS PREFER this tool over chaining single-source lookups for holistic company research and explains accepted input forms. It does not discuss when a narrower sibling like resolve_entity or deep_research might be more appropriate, so the when-not guidance is incomplete.

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

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

Annotations already indicate destructiveHint=true. Description adds context about clearing sensitive data and use cases, which is valuable beyond annotations.

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

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

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

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 destructive tool with one parameter and no output schema, description fully covers usage and context.

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

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

Schema coverage is 100% and description adds no additional meaning to the single parameter 'key' beyond what the schema provides.

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

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

Description clearly states 'Delete a previously stored memory by key.' with a specific verb and resource, and distinguishes from siblings like 'remember' and 'recall'.

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

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

Explicitly states when to use: when context is stale, task is done, or to clear sensitive data. Also mentions pairing with remember and recall, providing clear alternatives.

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

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

Annotations already provide readOnly, idempotent, and non-destructive hints. The description adds the process of fetching the page and extracting content, which complements annotations. No contradictions, but lacks details on error handling or rate limits.

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 with three core sentences followed by use cases. Every sentence adds value, and the structure front-loads key information efficiently.

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 no output schema, the description explains the output format and location. It covers the generation process and use cases adequately, though it omits potential edge cases like invalid URLs.

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 both parameters. The description does not add significant meaning beyond what the schema provides, maintaining 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 it generates a production-ready llms.txt file from a URL, listing the steps and output format. It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on file 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?

It provides explicit use cases (client site indexing, personal project, competitor audit), giving clear context for when to use. However, it does not mention when not to use or explicitly exclude alternatives among siblings, leaving some 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 already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds the return fields and clarifies that it lists active subscriptions (with optional inactive via parameter). This provides useful behavioral context 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 efficient sentences: the first describes the purpose and return fields, the second gives usage advice. No wasted 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?

The description fully covers the tool's function for a simple list operation: it names the return fields and mentions the optional parameter. No output schema exists, but the description compensates by listing the fields. The single parameter is well-documented in the schema.

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

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

Schema description coverage is 100% for the single parameter (include_inactive). The description does not add additional meaning beyond what the schema already provides. Baseline score of 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and lists the returned fields (id, type, params, created_at, last_fired_at, fire_count). This distinguishes it from sibling tools like subscribe and unsubscribe which have different actions.

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: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear guidance on when to use versus alternatives like subscribe or unsubscribe.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, so the safety profile is clear. The description adds 'great-circle' method, but does not disclose edge cases or precision limits.

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

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

Single sentence, no unnecessary words. Efficiently conveys the tool's 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?

The description is adequate for a simple tool with annotations and examples, but it lacks any mention of return value or error conditions. Since no output schema exists, this is a gap.

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

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

Schema description coverage is 0%, and the description does not explain parameter meanings. While parameter names and examples are self-explanatory, there is no mention of valid ranges or units, leaving gaps.

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

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

The description clearly states the tool computes the geographic great-circle midpoint between two latitude/longitude points. This distinguishes it from sibling tools like centroid (multiple points) and bounding_box (bounds).

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?

No explicit guidance on when to use this tool versus alternatives. The name and description imply it's for exactly two points, but there's no comparison to centroid or other spatial 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 provide little (all false), so the description carries the burden. It discloses the claim_token workflow ('Filing without an account returns a claim_token; pass it back later...'), rate limiting ('Rate-limited to 5 per identifier per day'), and cost ('Free; doesn't count against your tool-call quota'). It also mentions the team's daily digest reading and roadmap impact, giving a clear behavioral model.

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

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

The description is dense but every sentence provides a distinct, practical fact: use cases, exclusions, token workflow, rate limits, and quota. It is front-loaded with the core purpose and does not repeat schema content. Length is appropriate for the complexity of the tool.

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

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

Despite no output schema, the description explains what happens (token returned, status read) and gives operational context (daily digests, rate limit, quota). It covers prerequisites (account vs. no account) and content constraints, making it complete for an agent to decide and invoke correctly.

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

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

Schema coverage is 100% with detailed descriptions for each parameter, giving a baseline of 3. The description adds value by reinforcing the claim_token usage pattern and by advising message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), which the schema only partially implies. This extra guidance justifies a 4.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which clearly identifies the action (sending feedback) and the target (Pipeworx team). It enumerates specific feedback types (bug, feature/data_gap, praise), distinguishing it from sibling tools like ask_pipeworx which are for inquiries. The verb 'tell' and resource 'Pipeworx team' make 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?

Explicitly states when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog...' It also provides a clear when-not-to-use: 'if the tool came from a different MCP server... file it with that server instead.' This is textbook usage guidance with alternatives and exclusions.

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

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

Descriptions adds details beyond annotations: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This informs about data source, privacy, caching behavior. Annotations already cover safety, but description enriches transparency.

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?

Every sentence adds value. Front-loaded with core output, then use cases, then technical details. 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?

Despite no output schema, description explains returned fields (top tools, top packs, total call volume) and covers caching, data source, privacy. Complete for a simple read-only tool.

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

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

Schema coverage is 100% and enum values are listed. Description adds semantic context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps agents choose appropriately.

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 returns 'top tools, top packs, and total call volume' over a time window, using specific verbs like 'Returns' and 'Discovering'. It distinguishes from sibling 'discover_tools' by focusing on trending/call volume rather than static discovery.

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

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

Three explicit use cases are listed, giving clear context for when to use the tool. However, it does not explicitly state when not to use it or compare to alternatives like 'discover_tools'.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's mention of 'Test whether' aligns. However, it does not elaborate on return values or edge cases, but the annotations suffice for basic transparency.

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

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

A single, front-loaded sentence with no wasted words. Every part contributes to understanding the tool's purpose and parameter format.

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 test tool with three parameters and no output schema, the description covers the core functionality well. Lacks mention of return type (likely boolean), but examples aid understanding. Nearly 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 33% (only bbox described). The description adds meaning for bbox (format: minLat,minLon,maxLat,maxLon). Lat and lon lack additional description, but examples in schema provide context. Partial compensation for low 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 the tool's action ('Test whether'), the resource (lat/lon point and bounding box), and the bounding box format. It is distinct from siblings like 'bounding_box' and 'centroid'.

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?

No guidance on when to use this tool versus alternatives. For example, it doesn't explain how it differs from 'bounding_box' or when a point-in-bbox test is appropriate.

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

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

Annotations declare read-only and non-destructive. The description adds extensive behavioral context: internal checks (monotonicity, partition sum), semantic anchor (Jaccard similarity >= 0.30), partition filter (placeholder slugs), fill check (theoretical vs realizable edge), and response structure. No contradiction with annotations.

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

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

The description is verbose but well-structured: starts with a summary, then details modes and internal logic. It front-loads key information but includes extraneous details (SEMANTIC ANCHOR, PARTITION FILTER) that could be shortened.

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 tool with two modes, multiple internal algorithms, and no output schema, the description is extremely comprehensive. It explains response fields, fill check logic, trade recommendations, and even references a sibling tool for custom sizing.

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

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

Schema coverage is 100% with descriptions. The tool description adds extra meaning: clarifies that event expects a slug or full URL, topic is a seed question for cross-event search, and explains how each parameter affects the analysis.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between three modes (no args, event, topic) and differentiates from sibling tools like polymarket_fill_risk by explaining unique arbitrage detection logic.

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

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

Explicit guidance is given: no args for trending scan, event for specific market, topic for cross-event scan. Examples of event slugs and topic questions are provided. It also recommends an alternative tool for custom sizing ('use polymarket_fill_risk').

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's safe. The description adds rich behavioral context: caching (1h at KV level keyed on all knobs), response structure with diagnostics on why segments might be empty, and detailed derivation of edge metrics (e.g., Kelly fractions, edge_pp_net after slippage). 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 but well-organized with clear sections for model families, output fields, and parameter instructions. It front-loads the core purpose. However, some details (e.g., full explanation of each model) could be trimmed or moved to a more structured format for easier consumption by agents.

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

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

Despite no output schema, the description fully explains the response structure (by_segment segments, fed_candidates/fed_note, _diagnostics) and the fields carried by each opportunity (edge_pp_net, kelly_fraction, liquidity, etc.). Parameters are all described with practical guidance. The caching behavior is noted. The tool is self-contained for an agent to use correctly.

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

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

Schema coverage is 100%, baseline 3. The description goes far beyond schema descriptions: it explains how each parameter acts as a 'tradeable-edge knob', provides example values (e.g., 'Set to 5000 to drop thin-book opportunities'), and clarifies interactions (e.g., min_partition_leg_kelly vs. min_kelly for partition arbs). This significantly aids correct invocation.

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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today' discovery. It lists three distinct model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and explains their characteristics, making the tool's function precise and distinct from siblings like polymarket_arbitrage.

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

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

The description provides explicit context for when to use the tool ('what should I bet on today') and details parameter knobs for filtering (tradeable-edge filters, min_kelly, etc.). However, it does not explicitly state when NOT to use this tool compared to alternatives like polymarket_arbitrage or polymarket_fill_risk, though the uniqueness of the approach is implied.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds significant behavioral context: snapshots written on cache-miss, gaps mean no scan, decay from daily closes, and response details (tracked, expired, snapshot_dates). 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 structured: overall purpose, args, response format, and limits. It is front-loaded with the core question. Every sentence delivers new information, but could be slightly more concise by merging some repetitive points. Overall efficient.

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

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

Despite no output schema, the description fully explains the response objects: tracked[], expired[], snapshot_dates[], including fields like trend, decay_pp_per_day, lifespan_days. It also covers limitations and data sources. This is comprehensive for a tool with two simple parameters.

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

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

Schema coverage is 100% with both parameters described. The description adds value by clarifying defaults ('default 14', 'default 1wk') and constraints ('max 30'), and listing valid window values (24hr, 1wk, 1mo) beyond the schema's vague description. However, the schema already captures core semantics.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' and answers the specific question 'how long has this edge existed and is it shrinking?' The verb 'track' and resource 'edges over time' are well-defined, distinguishing it from siblings like polymarket_edges (current edges) and polymarket_arbitrage.

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

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

The description implicitly advises when to use: 'a fresh wide edge and a 3-week-old wide edge are different trades', indicating historical context is crucial. It also mentions limits like 60-day TTL and snapshot gaps. However, it lacks explicit when-not-to-use or direct reference to alternatives, but sibling differentiation is handled elsewhere.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds behavioral details like walking the order book ladder, returning specific fields, and highlighting thin-leg risks, completely consistent with annotations.

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

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

The description is long but well-structured with clear sections for each mode and important warnings. It front-loads the core purpose, though minor trimming could improve conciseness.

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

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

No output schema exists, but the description comprehensively lists all return fields for both modes, explains the verdict categories, and covers edge cases like forced directional risk, making it self-contained.

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

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

Schema coverage is 100%, but the description adds usage nuances like auto-detection of side in basket mode, interpretation of size_usd, and clamps ranges, enhancing semantic understanding.

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

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

The description clearly states the tool checks realizable-vs-theoretical edge against live CLOB depth. It distinguishes two modes (single-market and basket) and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) for context.

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

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

The description explicitly tells when to use this tool (before acting on arbitrage signals or edge trades above ~$500) and provides warnings about partial fills and unhedged positions, guiding correct usage.

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

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

The description goes far beyond the readOnlyHint/idempotentHint annotations by disclosing the token-overlap matching approach, the fact that unknown metric_type or match_subtype legs are never paired, and the precise meaning of null temporal_alignment. It also explains that compatibility_codes may be non-empty even when matched_pairs>0, and that fees are gross rather than net tradeable edge. This gives the agent accurate expectations about fallibility and interpretation.

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 tightly organized with uppercase section headers like TWO MODES, RESPONSE, and SAFETY FIELDS, and it front-loads the core purpose before caveats. Nearly every sentence carries an operational warning or interpretive rule that an agent needs, especially given the lack of an output schema. There is no filler or pure restatement of the title.

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 present, the description carries the full burden of explaining return semantics, and it does so comprehensively: top_spreads_pp, per-entry flags, compatibility_codes, temporal_alignment, skipped_unclassified, low_confidence_pairs, skipped_cross_type/subtype, and fees_note are all described. An agent can predict both the happy path and the edge cases before calling the tool.

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

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

Schema description coverage is 100%, and the schema already provides the topic list and example ticker/slug values. The description adds operational meaning by explaining how the two modes relate, that both modes run the identical token-overlap matcher, and that explicit parameters override the topic-mapped side. This adds context beyond the schema without needing to repeat syntax.

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 first sentence states a specific operation: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. This distinguishes the tool from same-venue siblings like polymarket_arbitrage by emphasizing the cross-venue scope. The description then reinforces the purpose by defining the response in terms of leg-by-leg prices and top_spreads_pp.

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

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

The description clearly explains two usage modes — pre-mapped topic shortcuts versus explicit kalshi_event_ticker + polymarket_event_slug pairings — and gives concrete guidance on when each is appropriate. It also warns that pre-mapped topics often return compatibility_warning and that pre-mapped does not mean tradeable. It does not explicitly name sibling alternatives, but the mode guidance is 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds scoping detail (identifier-based) and pairing guidance, providing useful context beyond annotations.

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

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

Two sentences are efficient, front-loaded with action, and contain no redundant information. Every sentence 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?

With a single optional parameter and rich annotations, the description covers all necessary behavioral context: what it does, when to use, scoping, and tool relationships.

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. Description adds the critical behavior of omitting key to list all keys, which is not in the schema description, enhancing understanding.

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

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

The description clearly states the tool retrieves a value by key or lists all keys, distinguishing it from siblings remember and forget. Specific verb and resource make 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?

Explicitly states when to use (look up context stored earlier) and names complementary tools (remember, forget). Does not explicitly exclude scenarios, 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?

Annotations already indicate read-only, idempotent, and non-destructive. Description adds side effects of mark_read flag and explains return format (source, citation_uri, payload). No contradictions.

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

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

Three sentences, each valuable. Front-loaded with main action. No wasted 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?

Describes return fields, filtering, and side effects. Mentions polling safety and alternative access. Missing pagination details but sufficient for a read 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%, description adds examples (e.g., 'sec_8k'), explains mark_read effect, and clarifies since as ISO timestamp. Adds meaning beyond schema.

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

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

Clearly states it pulls fired events from subscription feed, returns alerts with source, citation_uri, and payload. Distinguishes from siblings by mentioning polling and alternative GET endpoint.

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 filtering by type and/or since, setting mark_read, and notes polling works fine. Gives alternative access method. Lacks explicit when-not-to-use instructions but is sufficient.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description reveals that the tool fans out to three data sources (SEC, GDELT/GNews, USPTO) with fallback logic (GDELT preferred, GNews when rate-limited) and a soft-fail condition (USPTO). This adds valuable context about internal behavior not captured by annotations.

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

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

The description is a single coherent paragraph that front-loads example queries, then explains data sources and fallbacks, parameter details, and ends with a sibling comparison. Each sentence adds value, but the density could be slightly improved with bullet points or clearer segmentation.

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

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

For a read tool with three parameters and no output schema, the description covers source behavior, fallback logic, soft-fail conditions, and parameter formats. It addresses temporal boundaries (window) and provides a comparison with a sibling. Minor gaps: no mention of return structure details (e.g., 'pipeworx:// citation URIs' is listed but not explained), but overall sufficient.

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 enhances parameter understanding by providing practical examples for 'since' (ISO date, relative shorthand like '30d', '1y') and clarifying that 'value' accepts either ticker or zero-padded CIK. This reduces ambiguity and adds usage guidance beyond the schema's formal 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 starts with concrete example queries ('What's new with X', 'updates on Acme') and states it returns a change feed for a company over a window. It explicitly distinguishes from sibling tool entity_profile ('Use entity_profile instead when you want the static profile'). This provides a specific verb ('return changes') and resource ('company change feed'), with sibling differentiation.

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

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

The description explains when to use this tool ('What's new with X' queries) and when to use the sibling entity_profile ('static profile'). It also notes a temporal concern (USPTO soft-fails after May 2025). However, it does not explicitly state when not to use it or mention alternatives for other query types.

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 idempotent and non-destructive. Description adds value by explaining scope (key-value per identifier) and retention (24h for anonymous, persistent for authenticated users). 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?

Five focused sentences, each adding value. Front-loaded with core action, then expands with usage examples, persistence details, and related tool references. 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?

For a simple write tool with two parameters and no output schema, the description covers action, usage, persistence, and siblings. Minor omission like size limits not critical.

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%, baseline 3. Description provides concrete examples of key-value pairs (e.g., 'subject_property', 'target_ticker') that add meaning beyond 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 clearly states the tool saves data for reuse, with specific examples (ticker, address, preference). It distinguishes from siblings 'recall' and 'forget' by explicitly pairing with 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?

Explicitly says 'Use when you discover something worth carrying forward' and gives context about persistence differences based on authentication. No explicit when-not-to-use, but 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals subtle behaviors: graceful degradation when GLEIF/OpenFIGI are down, ambiguous matches returning `figi_candidates` rather than asserting, unresolved identifiers reported under `unresolved`, and internal cascading of lookups. This gives an agent a realistic model of what the tool will do.

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 content is information-dense and front-loaded with purpose, but it is delivered as one huge run-on paragraph with nested parentheticals, making it harder for an agent to parse. A bulleted or sectioned layout would improve scannability without losing detail.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so thoroughly: identifiers, source labels, `figi_candidates`, `unresolved`, and RxCUI citations. It also covers failure modes and cascading lookups, so an agent has what it needs to call and interpret 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?

Even with 100% schema coverage, the description adds substantial parameter meaning: it distinguishes the `value` input per type (ticker, CIK, ISIN, or name for company; brand or generic for drug), explains that ISIN resolves to the issuing legal entity, and warns against including trailing security-class words in bond names. This materially exceeds the schema.

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

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

The description opens with concrete example phrasings and a crisp verb-object: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It enumerates the exact identifier domains (CIK/ticker/LEI/FIGI/RxCUI) and implicitly distinguishes itself from sibling tools like entity_profile or compare_entities by focusing on identifier resolution.

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

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

It explicitly instructs 'Use FIRST whenever you have a name but need an ID,' giving a clear trigger condition. It also states supported types and input formats, but does not explicitly name exclusions or alternatives among the sibling tools, so it stops just short of the full when/when-not guidance.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it 'probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized' and mentions the return format (score, confidence, signal density). This goes beyond annotations by explaining internal mechanism and output structure. No explanation about potential costs or rate limits for Anthropic API, but sufficient for basic transparency.

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: first defines core action, second explains method and ranking, third gives use case and return summary. No filler words, front-loaded with purpose, and every sentence contributes value. Perfectly 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 adequately covers return values (ranked list with score, confidence, signal density). It also explains the dependency on ai_visibility_check and the optional Anthropic API key. For a tool with multiple entities, optional models and context, the description is complete and covers all necessary 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%, so baseline is 3. The description adds meaning beyond schema by noting that the first entity is treated as the 'subject' for narrative, and that the tool 'probes each entity with ai_visibility_check'. This clarifies the ordering and the internal process, which is not available from the 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?

The description clearly states 'Compare AI visibility across multiple entities side-by-side', specifying the verb (compare), resource (AI visibility of entities), and scope (multiple, side-by-side). It distinguishes from sibling 'ai_visibility_check' by focusing on comparison vs. single-check, and from 'compare_entities' by specifying AI visibility context.

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

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

The description explains the tool is 'Useful for competitive AI-marketing audits' and provides an example query 'does Claude know about us as well as our competitors?'. It implies single-entity checks should use ai_visibility_check instead. Lacks explicit when-not-to-use or alternative names, 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?

Beyond annotations (readOnlyHint, etc.), the description adds critical behavioral details: partial failures degrade gracefully, bundlephobia first measurement may take 5-30s, sources_failed will list timeouts, and the rest still returns. 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 a single well-structured paragraph that front-loads purpose, then usage, then return details, then limitations. Every sentence is informative and necessary.

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

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

Given no output schema, the description compensates by listing return fields (summary block, per-advisory, links, alternatives) and explaining partial failure behavior. It provides a complete understanding for agent 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%. Description adds value by noting scoped packages are accepted for 'package' and that 'version' defaults to latest when omitted. It also describes the structure of return fields, which is helpful since there is no output 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's a composite check for npm packages, covering license, advisories, version history, and bundle size. The verb 'scan' and resource 'dependency' are specific, and the tool is differentiated as a one-call composite.

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: 'Use whenever an agent asks 'is X safe / popular / small'' and gives an example. Also explains ecosystem limitations (NPM only in v1) and directs to alternatives for other ecosystems.

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 behavioral context beyond annotations: embedding model (BGE-base-en), chunking (500-char overlapping windows), character limit (200K chars) with truncation flag, and return format (passages with offsets and scores). 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?

Single paragraph is well-structured, front-loaded with purpose, then usage, then technical details. Every sentence adds unique value with no redundancy.

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

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

Despite no output schema, description thoroughly explains return values (passages with offsets and scores), technical details (embeddings, windowing, truncation), and pairing advice. Complete for a read-only search tool.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds value by providing example queries and clarifying that limit is max passages (1-20, default 5), exceeding 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?

Description clearly states 'Semantic search INSIDE a fetched record' with specific verb+resource. Distinguishes from siblings by referencing ask_pipeworx_grounded and explaining use case for large documents.

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 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded. Provides clear context and alternative, making it easy for an agent to decide.

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 a mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds behavioral details: OAuth requirement, SMS daily cap, webhook auto-disable after 10 failures, and the return of a subscription ID. It 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 a single paragraph that is dense with information but remains readable. It front-loads the core purpose. While it could benefit from structured bullets for readability, it is not excessively long for the complexity of the tool.

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

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

Given no output schema, the description adequately covers return behavior (subscription ID). It explains all subscription types, required params, delivery channels with examples and limitations. For a subscription creation tool with nested objects, it is thoroughly 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?

The schema covers 100% of parameters, but the description enriches every parameter with type-specific formats and examples (e.g., sec_8k items, polymarket_edge params, delivery channel limitations). This provides substantial meaning beyond the schema's generic descriptions.

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

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

The description explicitly states the tool's function: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It clearly identifies the verb (create/subscribe) and resource (subscription), and distinguishes itself from siblings like list_subscriptions and unsubscribe.

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

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

The description provides context on when to use the tool (proactive monitoring) and prerequisites (Pipeworx OAuth account). It details supported types and delivery channels with examples. However, it does not explicitly state when not to use it or suggest alternative tools for one-off queries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by explaining the return structure (category-bucketed examples with tool+argument shape) and the educational context, going beyond annotations.

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

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

The description is a single paragraph that packs a lot of information (alternative phrasings, behavior, input options, output nature). It is efficient with no wasted words, though could be slightly more structured with bullet 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 the single optional parameter, no output schema, and comprehensive annotations, the description fully covers the tool's purpose, input, output, and usage context. It leaves no gaps for an agent to misunderstand.

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

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

With 100% schema description coverage, baseline is 3. The description adds meaning by listing the possible topic values and explaining that omitting gives a cross-category spread, which is not in the schema's 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 returns category-bucketed example questions showing what Pipeworx can do, and positions it as an onboarding entry point. It distinguishes from siblings like ask_pipeworx and entity_profile by emphasizing examples and 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?

The description explicitly says 'Call with no arguments for the full spread' and 'pass `topic` to focus'. It also says 'Use this FIRST when you do not yet know what Pipeworx can do for you', providing clear when-to-use guidance.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds critical context: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This clarifies the non-destructive, soft-delete behavior and links to a sibling tool.

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 that are front-loaded and efficient. Every sentence adds unique information: purpose, ownership constraint, and behavioral nuance. No wasted 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?

For a simple single-parameter tool with no output schema, the description covers purpose, usage condition, and behavioral effect. It references relevant sibling tools and provides complete guidance.

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

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

With 100% schema coverage, baseline is 3. The description adds value by noting the id is a UUID and that it comes from subscribe, helping the agent understand the parameter's origin and format.

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 'Cancel a subscription by id', using a specific verb and resource. It naturally distinguishes from sibling tools like subscribe and list_subscriptions.

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

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

The description explains ownership enforcement ('you can only cancel your own subscriptions'), which guides when to use. It doesn't explicitly mention when not to use, but the condition 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?

The description goes far beyond annotations by detailing the return structure (verdict values, actual value with citation, reasoning), the special meanings of could_not_verify and unsupported, and how to interpret error payloads. It also reveals the tool replaces 4–6 sequential calls, giving useful context about its internal operation.

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

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

The description is dense but well-organized, opening with trigger phrases and then covering usage, return values, and edge cases. The 'IMPORTANT for callers' section is appropriately highlighted. A bit long, but 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 no output schema and the tool's multi-path complexity, the description fully covers when to use it, what verdicts to expect, how to interpret edge cases, and parameter behavior. It leaves no important aspect unexplained for effective 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%, but the description adds meaningful operational detail for tolerance_pct, such as overriding the implied tolerance, the recommended range for hallucination detection, and the default cap. It also gives concrete claim examples for the claim 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 identifies the tool as a claim-verification system, with specific trigger phrases ('fact check', 'verify the claim that...'). It distinguishes itself from siblings like ask_pipeworx and deep_research by focusing on judging factual claims and describing two distinct verification pipelines (SEC EDGAR for financials, grounded pipeline for everything else).

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 whenever the agent needs to check whether something a user said is factually correct' and gives examples of applicable claims. It explains the internal routing (financial vs. non-financial) but does not name alternative sibling tools for queries that are not claim verification, or explicitly state 'do not use when...'.

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