Opentopodata

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: the default free model (Workers AI Llama-3.3-70b), the BYO-key billing model for Anthropic, and the per-model return 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 compact and information-dense: every sentence contributes. It front-loads the core purpose, then adds model defaults, billing, return format, and use cases without redundancy or filler.

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

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

Given the tool's moderate complexity (4 params, no output schema), the description covers the main aspects: purpose, use cases, parameter behavior (default model, API key), and partial return structure. It could go further by detailing the combined view, but this is a minor gap.

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

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

The input schema has 100% parameter coverage, so the baseline is 3. The description adds meaning beyond the schema by explaining the default model (workers-ai) and the billing implications of passing _apiKey ('BYO key — you pay Anthropic directly for those calls'), which goes beyond the schema's 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 uses a specific verb+resource combination: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It clearly states the tool's function and output, and distinguishes it from siblings by focusing on multi-model knowledge scoring rather than single Q&A or entity profiles.

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

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

The description provides clear context for when to use the tool: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly mention when not to use it or name alternative tools, so it stops short of a 5.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the description's additions are pure bonus: auto-routing with automatic argument-filling, the structured-output contract with stable pipeworx:// citation URIs, the "one fast call" performance trait, and the nuance that live-news routing is already bundled in. Minor deduction only because rate limits, auth requirements, and retry behavior go unmentioned, though these may be irrelevant for this call pattern.

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?

Perfectly front-loaded — the single most important guidance ("PREFER OVER WEB SEARCH") is the first three words, followed by the domain list, examples, and only then alternatives. The logical flow from preference → mechanism → triggers → examples → escalation rules is easy to follow even though it's a dense wall of text. The trigger-phrase list and trailing news clarification are mildly redundant with earlier statements, keeping this from a 5.

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

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

For a tool with one effective string parameter, fully-specified safe-operation annotations, and no output schema, the description is effectively complete: it covers when to use the tool, what to send, what to expect back (structured answer + pipeworx:// URIs), when to escalate to either of two named alternatives, and even a subtle edge case (breaking-news-style questions should still route here). The only sibling not explicitly differentiated is ask_pipeworx_beta, whose purpose is obvious from its name.

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), so the description's examples and domain enumeration (SEC, FDA, FRED, USPTO, ATTOM, clinical trials, crypto, sports, academic) add genuine semantic richness beyond the terse "Alias for question" entries. The alias parameters (q, text, input, query, prompt) are self-explanatory in the schema itself. The description's added value is the curated list of valid question domains and the worked example queries.

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?

Opens with a clear action directive ("PREFER OVER WEB SEARCH") and precisely states what the tool does: routes natural-language questions across 5,564 tools and 1,462 sources, returning structured answers with pipeworx:// citation URIs. Explicitly claims the default entry-point role and names the two siblings it could be confused with (ask_pipeworx_grounded, deep_research), making its purpose unmistakable.

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

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

Lists explicit trigger phrases ("what is", "look up", "find", "get the latest", "how much", "current") and concrete examples ("current US unemployment rate", "Apple's latest 10-K", "patents Tesla was granted last month"). Even provides escalation rules: use ask_pipeworx_grounded for verbatim-evidence answers, deep_research for multi-part fan-out. Perfect when-vs-when-not coverage.

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 beyond annotations by explaining the beta status, that no candidate is active (so it currently matches ask_pipeworx), and that it's a full working router with no fallback. It also discloses that it's under test for routing improvements, which is valuable behavioral context not captured in 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 informative and front-loaded with the beta identity and equivalence to ask_pipeworx. However, it repeats the idea of identity ('identical universal router' and 'Use it exactly like ask_pipeworx') somewhat redundantly, though this is minor and the structure is clear.

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

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

Given the complexity (a router with 5,564 tools), the description is quite complete: it explains the exact relationship to ask_pipeworx, the current inactive candidate state, and confirms it's a full working router. No output schema exists, but the description says the response shape is identical, which suffices.

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

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

The input schema already provides full descriptions for all parameters (100% coverage), including aliases. The description adds minimal extra semantic meaning beyond stating 'same arguments' as ask_pipeworx, so it meets the baseline without compensating further.

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

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

The description states this is the beta version of ask_pipeworx, a universal router with 5,564 tools, and explicitly says it currently matches ask_pipeworx exactly. This clearly defines the tool's function and distinguishes it from its stable sibling.

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

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

Provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. This tells agents when to choose this beta over the stable version and clarifies its experimental purpose.

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), the description discloses the tool's refusal behavior, return structure with specific fields (answer, evidence, confidence, etc.), and the additional LLM call cost. It even lists refusal reason codes, giving the agent a complete picture of what happens on failure. This goes far beyond what annotations alone provide.

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 information-dense but organized logically: purpose, mechanism, return format, usage guidance, and cost trade-off. While it's a longer paragraph, every sentence adds value. It is front-loaded with the core purpose sentence, making it easy to scan. Slightly verbose but not wasteful.

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

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

Given the lack of an output schema, the description fully explains the return values, including the success response fields and all possible refusal reasons. It also covers the operational context (routing, extraction, cost). For a tool with this complexity (handling 5,564 tools across 1462 sources), the description provides a complete mental model without leaving gaps.

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

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

The input schema fully documents the single 'question' parameter and its aliases (q, text, input, query, prompt). The description adds no additional semantic meaning about parameters—it only mentions natural language usage implicitly. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It distinguishes itself from the sibling ask_pipeworx by explaining the same routing but then 'EXTRACTS the answer using ONLY what the tool result contains,' making the unique value proposition explicit.

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 on when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts...' It also provides a clear trade-off and alternative: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This directly addresses when to choose this tool over its sibling.

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

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

The annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description goes far beyond by disclosing resolver contract (market_match_confidence, match_score, alternatives), low-confidence short-circuit behavior, closed/dead market handling, wide-spread tradeability flags, cancellation-rule parsing (including flat-50¢ risk), and fallback fields for news sources. This extensive behavioral context is not present in annotations and is highly valuable.

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 a clear first sentence and organized into labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.), which aids skimming. It is quite long, but every sentence carries useful information about behavior, safety, and edge cases. Minor redundancy (e.g., repeating 'both routes are BLOCKING') could be tightened, but structure remains strong.

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 bears the full burden of explaining return shapes, and it does so comprehensively: result.market fields, result.analysis with model probability and edge, result.evidence keyed by source, parent_event extractor, news fallback fields, and safety mechanisms. It also covers cancellation-rule risk and closed-market paths, making it exceptionally complete for a tool of this complexity.

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

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

Schema coverage is 100% with detailed descriptions for all three parameters (market, depth, include_raw). The tool description does not add new parameter-specific semantics beyond what the schema already provides; it mentions fan-out examples but doesn't clarify depth or include_raw behavior beyond the schema. Thus baseline 3 is appropriate.

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

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

Description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly differentiates from sibling tools like polymarket_edges or polymarket_arbitrage by focusing on data-fan-out research with classifier categories. Examples of use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') further ground its purpose.

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

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

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".' Provides concrete fan-out examples for several bet types (BTC, Fed, Hormuz, Yankees, etc.), giving clear context. However, it does not name specific alternative tools to prefer for edge-finding or arbitrage, so it slightly misses the 'when-not-to-use' part.

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, the description discloses data sources (SEC EDGAR/XBRL, FAERS), specifics like off-calendar fiscal year handling, sorting behavior by primary metric, and output format with piped citation URIs. This is substantial value-add with no contradiction to readOnly/idempotent hints.

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

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

The description is dense but every sentence carries essential information: purpose, usage priority, type-specific behavior, sorting, output format, and efficiency gains. It is well-structured with front-loaded examples and no filler.

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

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

Given there is no output schema, the description adequately covers return values ('paired data + pipeworx:// citation URIs'). It also covers scope limits (2–5), data sources, and sorting, making the tool's behavior fully comprehensible for an agent.

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

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

Schema coverage is 100%, but the description adds deep meaning: it explains the semantic difference between 'company' and 'drug' (what data each pulls), and clarifies the expected format for 'values' (tickers/CIKs vs drug names) with examples. This goes well beyond the schema's minimal descriptions.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in a single parallel call, with concrete query examples ('X vs Y', 'which is bigger'). It distinguishes itself from siblings like entity_profile by explicitly framing this as a multi-entity comparison rather than a single-entity lookup.

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: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and states it replaces 8–15 sequential lookups. It also explains when to use type='company' vs 'drug', giving clear conditions for each variant.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the 'DEM' context but does not disclose additional behavioral traits like whether the list is exhaustive, sorted, or subject to pagination. This meets the minimum bar given strong 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, focused sentence with no waste. It is front-loaded with the action and resource, making it immediately actionable.

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 has no parameters and an output schema exists, the description is sufficiently complete. It clearly states what the tool returns (a list of DEM datasets), and the output schema likely provides details on the return shape. No additional context is needed.

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

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

The tool has zero parameters, and the input schema is an empty object with 100% coverage. Per the baseline for 0 params, a score of 4 is appropriate; the description does not need to add parameter 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 uses a specific verb ('List') and a specific resource ('available DEM datasets'), clearly distinguishing this tool from siblings like 'elevation' or 'ask_pipeworx'. Even though the tool name and title are generic, the description adds the specificity of 'DEM datasets'.

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 no guidance on when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. There is no indication of how it relates to sibling tools such as 'elevation', which would be its natural companion.

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

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

Annotations already mark it read-only, open-world, idempotent, and non-destructive; the description adds rich behavioral context: auth gating, parallel decomposition, return packet structure with gaps[], contradictions[], hops, citation resolvability, semantic excerpting, and latency expectations. Nothing contradicts 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 dense and every sentence adds operational value: auth, tool distinction, execution model, output shape, latency, and edge cases. Front-loaded with the account requirement and the most critical alternative-tool guidance.

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

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

With no output schema, the description fully explains return values: verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], and hop field. It also covers performance expectations and data-source coverage, making it complete for a complex research tool.

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

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

Schema coverage is 100%, with both question and depth described in detail, so the description adds little beyond the schema. It reinforces that question can be broad/multi-part, but this is already in the schema. Baseline 3 is appropriate because the schema carries the parameter 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?

Description clearly states it performs grounded multi-source research across Pipeworx's 1462 structured data sources in ONE call, and differentiates itself from ask_pipeworx (single lookup vs. broad multi-part research). The verb-resource pairing is specific and the scope is made explicit.

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 (broad/multi-part questions over structured data) and explicit when-not-to-use (single lookups, breaking/current-news topics), naming ask_pipeworx as the alternative. Also states account requirements and fallback behavior if not signed in.

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 flag read-only, idempotent, and non-destructive behavior. The description adds valuable context about return format (top-N tools with full schemas and curated examples) and 'no second schema lookup needed,' which goes beyond annotations without contradicting them.

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

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

The description is three sentences, front-loaded with a clear purpose, followed by a domain list and return details, and closes with a usage instruction. Every sentence adds value with no redundancy or filler.

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

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

For a discovery tool with no output schema, the description adequately covers return values, usage scenarios, and the kinds of queries it accepts (via examples in the schema). It is complete for its complexity and leaves no major gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level semantics beyond what the schema already provides; it mentions 'top-N' but the limit parameter is fully defined in the schema. Since the schema handles parameter meaning, no extra credit is needed.

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 'Find tools by describing the data or task,' which is a specific verb+resource statement. It clearly distinguishes this as a meta-tool for tool discovery among domain-specific siblings, and the domain list reinforces the scope.

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 states 'Use when you need to browse, search, look up, or discover what tools exist' and instructs 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides both positive and negative usage context, effectively guiding selection versus directly using a known tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the read-only nature. The description adds the 'Up to 100 locations per request' limit, which is a valuable rate constraint beyond what annotations provide. No contradiction detected.

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 one compact sentence of eight words: 'Elevation at points. Up to 100 locations per request.' It is front-loaded, directly conveys the core function and key limit, and contains zero 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?

The tool is simple with only one required parameter, an output schema is present, and the input schema is fully described. The description provides the essential usage context and the batch limit. Nothing critical is missing given the richness of structured data, though it is understandably brief.

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 each parameter (format, dataset, samples, locations) already described in the input schema, including defaults and accepted shapes. The description adds no additional parameter-specific meaning, so the schema carries the full burden and 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?

The description states the tool returns elevation at points and caps at 100 locations, making its function immediately clear. It lacks an explicit verb like 'get' but is unambiguous and no sibling tool overlaps, so no differentiation is needed.

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

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

The description gives clear context: used for elevation lookup at specified points, with a 100-location upper bound implying batch use. There are no alternative tools with similar purpose in the sibling list, so exclusions aren't necessary. The limit helps the agent decide when this tool fits.

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?

Despite comprehensive annotations (readOnly, openWorld, idempotent), the description adds behavioral details: patents soft-fail until May 2025, GDELT→GNews fallback, and return specifics like 'up to 5' filings with URIs. No contradiction with annotations.

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

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

The description is lengthy but organized, front-loaded with trigger examples, and every clause covers a distinct aspect (data sources, output structure, limitations). Slightly verbose but earns its place for a complex tool.

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

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

No output schema exists, but the description enumerates all returned components (cik, company_name, recent_filings, fundamentals, patents, news mentions, LEI) along with constraints. This is sufficient for an agent to predict the tool's behavior.

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

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

Schema descriptions fully cover both parameters (type and value) with identical wording to the description. The description adds no new parameter semantics beyond the schema's zero-padded CIK and name-unsupported guidance, so baseline 3 applies.

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

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

The description clearly states the tool's core function: 'full cross-source profile of a US public company in ONE parallel call.' It names specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and distinguishes from sibling tools by directing preference over chaining single lookups.

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

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

Explicit guidance is given: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states the limitation for names and directs to resolve_entity as an alternative.

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

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

Annotations already include destructiveHint: true and idempotentHint: true, so the description only needs to add context. It does so by saying the tool 'clears sensitive data' and deletes 'previously stored memory,' reinforcing the destructive nature without contradicting annotations. Lacks details on irreversibility but this is a simple delete.

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 the primary purpose, followed by usage guidance. Every sentence adds value; 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 delete tool, the description covers what (delete a memory), when (stale/done/sensitive), and how it relates to siblings. The annotations and schema provide safety and parameter details. No return format needed; no obvious gaps.

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

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

Schema description coverage is 100%, with the 'key' parameter documented as 'Memory key to delete.' The description's 'by key' adds no new semantics beyond the schema, so baseline 3 applies.

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

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

The description clearly states the action: 'Delete a previously stored memory by key.' This is a specific verb+resource, and the explicit mention of deleting a memory distinguishes it from sibling tools like 'remember' (store) and 'recall' (retrieve).

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

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

The description provides explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also names related tools with 'Pair with remember and recall,' making the usage context fully clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds value by revealing the workflow (fetches the page, extracts title/description/key links) and the exact output shape (single text blob at site-root/llms.txt). It doesn't cover error cases or rate-limit behavior, but the annotations cover the safety profile, so this is solid.

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

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

Two tight sentences: the first states the action, process, and output; the second lists real-world use cases. No fluff, no repetition of schema fields. 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 the tool's simplicity (2 params, no output schema, safe annotations), the description sufficiently covers the workflow, input requirements, output format, and deployment context. It could mention failure modes (e.g., invalid URL, unreachable site), but for this low-complexity tool, it is largely complete.

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

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

Schema coverage is 100%: url and max_links both have descriptive comments including defaults (default 25, max 50). The description loosely mentions 'any URL' and 'standard llms.txt markdown format', but doesn't add substantive parameter-level detail beyond the schema. With such high schema coverage, a baseline 3 is appropriate.

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

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

The description opens with a specific verb-object pair: 'Generate a production-ready llms.txt file for any URL' and then details the process (fetches, extracts, emits) and the target format. This distinguishes it clearly from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on auditing rather than 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?

The 'Useful for' list gives concrete adoption scenarios: indexing a client's site, drafting for one's own project, or auditing a competitor's AI visibility. This provides clear when-to-use context, though it doesn't explicitly contrast with sibling tools or state when not to use it.

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, so the agent knows this is a safe read operation. The description adds the caller scoping and the return fields, plus the notion of 'active' subscriptions, which enriches the behavioral model without contradicting 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 sentences achieve both clarity and economy: first states the primary purpose and return payload, second states practical usage scenarios. No filler or redundant phrasing.

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 list tool with one optional boolean parameter, the description provides the return fields and usage guidance. No output schema exists, but the description compensates by listing the exact fields. The context is complete for an agent to select and invoke this tool effectively.

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

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

The schema covers the only parameter (include_inactive) with a clear description, so the description doesn't need to add much. It doesn't mention the parameter, but with 100% schema coverage, the baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description opens with 'List the caller's active subscriptions', which is a specific verb and resource, clearly distinguishing it from sibling tools like subscribe and unsubscribe. It also enumerates the exact fields returned (id, type, params, etc.), leaving no ambiguity about the tool's function.

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: 'review what you're monitoring before adding more or to find an id to cancel.' This gives actionable context, though it doesn't explicitly mention alternatives or when not to use it. Still, the guidance is clear and useful.

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 discloses several non-obvious behaviors beyond annotations: anonymous filing returns a claim_token that can be reused later, rate limits (5/day), daily digest read by the team, and no effect on quota. Annotations only indicate readOnly=false, so the description adds substantial transparency about side effects.

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 dense paragraph, but it is logically organized: purpose, usage criteria, exclusions, token workflow, and operational notes. It is longer than typical but every sentence carries meaningful guidance; slight loss for lack of visual 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?

Given the tool's optional-nested parameters and no output schema, the description fully compensates by explaining the return behavior (claim_token), read-reply workflow, and rate limiting. It also covers edge cases, making it complete for an agent to use autonomously.

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, but the description adds essential usage context, especially for claim_token (passing only that argument reads prior report) and message (be specific, don't paste prompt). It also clarifies the 'type' enum semantics via the description, making the parameters more actionable.

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

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

The description clearly states that this tool sends feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It distinguishes itself from sibling tools by focusing on internal Pipeworx tool reporting and explicitly scoping feedback to this connection's tools.

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

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

Provides explicit criteria for when to use (bug, feature/data_gap, praise) and, crucially, when not to use (feedback about other MCP servers). Also explains the claim_token workflow for following up, making the decision boundary very clear.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable context: self-aggregating signal, derived from CF analytics-engine, no PII, just (pack, tool, count), and caching behavior (5min-1h depending on window). This goes beyond the annotations without contradicting them.

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 organized with a purpose statement, a returns list, and a bulleted 'Useful for' section. While slightly longer than minimal, every sentence adds information—including the derivation and caching notes. It is front-loaded with the core purpose and remains well-structured.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete: it states what is returned (top tools, packs, total volume), the time windows, the data source, and the non-PII nature. It does not describe exact output formatting, but without an output schema, this is acceptable for a read-only analytic tool.

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

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

The input schema already covers the single 'window' parameter with enum and description (100% coverage). The description further explains window semantics: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' adding interpretive value 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 function: showing what other AI agents are calling on Pipeworx right now, returning top tools, top packs, and total call volume. It uses a specific verb ('returns') and resource ('trending usage'), and this distinguishes it from siblings like 'discover_tools' by focusing on observational analytics rather than 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?

The description provides explicit 'Useful for' contexts: discovering hot data sources, confirming canonical tool choice, and checking alignment with agent needs. It does not mention alternatives or when not to use it, but the guidance is clear and actionable, covering three concrete scenarios.

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

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

Beyond the readOnly/idempotent annotations, the description reveals extensive behavioral details: the 3pp deviation threshold for partition signals, the Jaccard similarity floor of 0.30 for cross-event pairing, the 20% placeholder filter that nulls arb signals, and the fill-check logic warning that realizable_edge_pp <= 0 means the edge is not in the book.

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 dense and well-structured with clear labels: SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK. Each sentence adds substantive information; there is no filler. It is front-loaded with the core purpose and then methodically explains modes, filters, and response details.

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

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

With no output schema, the description fully documents the response shape (opportunities[], partition_check, fill check details). Given the tool's complexity and optional parameters, the description covers input modes, internal checks, output semantics, and a critical safeguard (don't trade when realizable_edge_pp <= 0), making it complete for an agent to invoke and interpret results.

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

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

Although schema coverage is 100%, the description enriches the parameters with concrete slug examples, URL acceptance, and seed-question examples. It clarifies how 'event' and 'topic' map to different scanning modes, adding practical meaning beyond the schema text.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the three invocation modes (no args, event, topic) and states what each does, leaving no ambiguity about the tool's purpose.

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

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

The description gives explicit when-to-use guidance for each mode: no args for trending scan, 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also points users to polymarket_fill_risk for custom sizing, making the alternative tool explicit.

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 provides extensive behavioral detail beyond annotations: it explains what each model family does (e.g., 'crypto_price (lognormal barrier from 90d FRED log-returns)'), how opportunities are filtered (e.g., 'placeholder-slug filter drops will-person-X / will-team-Y / will-manager-Z'), the 24h-move warning, the fact that partition arbs return kelly_fraction_half=0 by design, and the KV-level caching keyed on knobs. This goes far beyond the read-only/idempotent hints already provided 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 dense wall of text with many implementation details (e.g., 'per-sport α (tennis 1.02, soccer 1.10, MMA 1.15, default 1.0)' and 'gates relaxed Run 8 from prior 85%/5%/50:1') that are not necessary for selecting or invoking the tool. While some structure exists in uppercase labels like 'TRADEABLE-EDGE KNOBS' and 'RESPONSE TOP-LEVEL', the length could be significantly reduced without losing essential invocation guidance. It is front-loaded but over-specified.

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

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

Given the tool's complexity (9 parameters, three model families, rich output structure) and the absence of an output schema, the description is highly complete. It enumerates the response segments (by_segment, fed_candidates/fed_note, _diagnostics), explains what each opportunity carries (edge_pp_net, kelly_fraction, market.liquidity, etc.), and describes the diagnostics so callers understand why a segment might be empty. It also notes the caching behavior. This fully equips an agent to use the tool.

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

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

Schema coverage is 100%, so parameters are already described. The description adds meaningful context for several knobs, such as explaining that min_partition_leg_kelly applies to per-leg Kelly because 'Partition arbs always return kelly_fraction_half=0 at the parent level by design', and that min_kelly never filters partitions. It also clarifies that slippage_pp is subtracted before ranking. This adds value beyond the schema's 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 opening sentence clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also distinguishes itself with the 'what should I bet on today' use case and describes three specific model families, separating it from siblings like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description gives clear usage context: 'Built for "what should I bet on today"' and explains that it avoids paging hundreds of markets. It also provides exclusions, such as Fed bets being 'excluded from ranking' due to unreliable signals, and explains when filters like min_liquidity and max_spread_pp should be used. However, it does not explicitly name alternative sibling tools or state 'when not to use this tool' beyond mentioning Fed bets.

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 include readOnlyHint=true and idempotentHint=true, and the description adds substantial behavioral context: how snapshots are produced (cache-miss), response semantics (tracked vs expired), data gaps, and limitations (60-day TTL, daily closes). 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 longer than average but organized into Args, RESPONSE, and LIMITS sections. Every section contributes essential operational detail, particularly the response structure which compensates for the lack of an output schema. The analogies are brief and help interpretation without bloating the text.

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

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

Given the absence of an output schema, the description thoroughly documents the response shape (tracked, expired, snapshot_dates) and all relevant edge cases (gaps, TTL, daily-close basis). It is self-sufficient for an agent to understand what the tool returns and under what constraints.

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

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

The input schema already documents both parameters fully (days with default/clamp, window with values and default). The description restates these defaults and adds the 'snapshot family' concept, but does not add material new semantics beyond the schema. Baseline 3 is appropriate for 100% schema coverage.

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

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

The description states a specific purpose: 'Edge persistence and decay telemetry' and answers a concrete question ('how long has this edge existed and is it shrinking?'). This clearly distinguishes it from the sibling polymarket_edges tool by focusing on historical snapshot persistence rather than current edges.

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

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

The description gives an explicit use case and explains why persistence matters for decision-making. It doesn't explicitly mention when not to use the tool or name an alternative, but the purpose framing and snapshot-based nature make the usage context clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context beyond these: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), identifies thin_legs and forced_directional_risk, and warns about partial basket fills converting arb into unhedged directional position. It also clarifies the REQUIRES constraint for market/event, which is not in annotations. No contradiction with annotations.

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

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

The description is long and dense, but well-structured with uppercase keywords (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) and clear segmentation. Every sentence adds value, though it could be trimmed slightly without losing essential context. The front-loaded purpose and usage guidance make it effective despite 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 having no output schema, the description enumerates return values for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk). It also covers prerequisites, parameter interpretation, and real-world risk context. This is fully complete for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains the dual meaning of 'side' in single-market vs basket mode, including the default auto behavior (sell if partition sum > 1, buy if < 1). It also clarifies 'size_usd' interpretation (max spend on buys vs target proceeds on sells; settlement notional in basket mode), and the mutual exclusivity requirement of market/event. This goes beyond the schema's descriptors.

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 a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' with a specific verb and resource. It distinguishes between single-market and basket modes, and the stated outputs (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.) clarify the exact purpose. It also differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk and execution quality.

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

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

Explicitly instructs when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (theoretical overround on thin books is not capturable, partial fills convert arb into unhedged directional position). This gives clear context and identifies the risk scenarios where the tool is essential.

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 by detailing safety fields, compatibility warning conditions (matched_pairs:0 with skipped_cross_type vs. no skipped_cross_type), temporal alignment logic, and skipped_cross counters. It also discloses that pre-mapped topics often return warnings, giving realistic expectations about output behavior. No contradiction with readOnlyHint/idempotentHint 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 distinct sections (modes, response, safety fields, warnings). It is front-loaded with the core definition and uses uppercase labels for clarity. Every sentence adds meaningful context, though some details could be condensed without losing value.

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

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

With no output schema, the description fully explains the response structure: leg-by-leg prices, matched_spread with top_spreads_pp, and the safety fields. It covers edge cases, temporal alignment, and limitations, making the tool usable without additional documentation. The description is complete for a complex cross-venue comparison tool.

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

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

The input schema already covers all three parameters with 100% description coverage. The tool description adds value by explaining how the two modes interact: topic auto-fetches matching events on both venues, while explicit ticker/slug override the topic-mapped side. It also clarifies the allowed topic values and the purpose of custom pairings, which is beyond the schema's basic 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 defines the tool as computing a cross-venue spread between Kalshi and Polymarket for the same resolving question. It uses specific terminology and identifies the resource (two venues) and the core operation (spread calculation), distinguishing it from sibling tools focused on single-platform analysis or other arbitrage types.

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 two usage modes (topic shortcuts and explicit ticker/slug pairing) and provides context on when spreads are meaningful vs. when compatibility warnings fire. It warns that most pre-mapped topics are not tradeable, which is useful guidance, but it does not directly compare against sibling tools or state explicit when-not-to-use conditions beyond the built-in warnings.

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 valuable behavior beyond annotations: the optional key argument lists all keys, storage is 'scoped to your identifier', and it explicitly pairs with remember/forget. This gives a fuller behavioral picture without contradicting 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 three sentences, starts with the core action and key behaviors, then provides use-case examples, scoping, and related tools. Every clause adds value with no filler or repetition.

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

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

For a single-parameter tool with strong annotations and no output schema, the description is complete: it covers what the tool does, when to use it, scope, and how it relates to remember and forget. The provided examples and explanation of the list-all-keys mode ensure an agent understands both invocation patterns.

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

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

Schema coverage is 100% with a clear description for the 'key' property ('omit to list all keys'). The description reinforces this by explaining 'omit the key argument' and provides concrete examples (user's target ticker, an address) that give context beyond the schema. Since schema already documents the parameter well, the description adds useful framing but not entirely new 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 'Retrieve a value previously saved via remember, or list all saved keys' – a specific verb and resource. It distinguishes from siblings by explicitly naming 'remember' and 'forget' as partner tools, and clarifies the two invocation modes (retrieve vs. list).

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 the tool: 'Use to look up context the agent stored earlier ... without re-deriving it from scratch.' It also mentions the companion tools 'remember' and 'forget', providing clear usage context and integration 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?

The annotations declare readOnlyHint=true, but the description explicitly states that setting mark_read:true 'flag returned events read so the next call only shows newer ones'—a mutation of persisted state. This directly contradicts the readOnlyHint annotation. No other behavioral context can compensate for this contradiction, so the score must be 1.

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

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

The description is three sentences, front-loaded with the primary action, and every clause adds value—event payload details, filter guidance, mark_read side effect, and the alternative HTTP feed. No wasted words or repetition of schema content.

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?

Although there is no output schema, the description explains return values (source, citation_uri, raw payload) and covers filters, mark_read behavior, and polling suitability. It does not mention unread_only or limit defaults, but these are already in the schema. The main gap is the unresolved contradiction with annotations, which affects trust but not raw completeness.

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

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

The input schema already documents all parameters at 100% coverage. The description adds meaningful semantics: it gives an example filter ('sec_8k'), explains that 'since' is an ISO timestamp, and clarifies that mark_read affects future calls. This goes beyond the schema's basic parameter descriptions, earning a 4.

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

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

The description opens with a specific verb and resource: 'Pull fired events from your subscription feed.' It clearly states what the tool does and distinguishes it from siblings like list_subscriptions by focusing on alert event payloads rather than subscription management. The scope ('most recent alerts') and intent are unambiguous.

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

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

The description gives clear usage context: filters (type, since), mark_read behavior, and that polling is acceptable. It also names an alternative endpoint for scripts/dashboards. However, it does not explicitly state when to use this tool over alternatives or provide exclusion criteria, only implying the primary use case.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, and the description adds substantial context: the parallel fan-out to multiple sources, the GDELT→GNews fallback trigger, the USPTO soft-fail due to PatentsView sunset, and the output shape including citation URIs. This goes well beyond what annotations alone 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 a solid paragraph but packs a lot of information efficiently. It leads with user-facing query examples, then explains sources, parameters, and output. Every sentence contributes value, though the density may require careful reading. Slightly long but well-structured.

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 thoroughly covers return values (changes[] grouped by source, total_changes, citation URIs). It also covers fallback behavior, source limitations (USPTO soft-fail), and parameter variations. This is complete for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it provides concrete examples for `value` (ticker vs CIK), explains `since` formats with shorthand examples, and clarifies the `type` enum (only 'company' supported). This enriches the raw 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 identifies recent_changes as a change feed for a company over a time window, fanning out to SEC EDGAR, GDELT/GNews, and USPTO. It uses specific verbs ('Fans out', 'Returns structured changes') and explicitly contrasts with entity_profile, making its unique role clear.

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

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

The description provides extensive usage guidance: example query phrasings, explicit instructions for the `since` parameter (ISO or relative shorthand), fallback behavior (GDELT preferred, GNews when rate-limited), and a direct recommendation to use entity_profile instead when a static profile is needed. It even suggests '30d' or '1m' for typical monitoring.

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 non-read-only, idempotent operation. The description adds valuable context: key-value scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. It doesn't mention overwriting behavior on duplicate keys, but the idempotent hint mitigates this concern.

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 that are information-dense without fluff. First sentence states the core purpose, second gives usage guidance, third covers scoping and persistence. Every sentence adds unique value.

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

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

For a simple 2-parameter save operation with no output schema, the description covers purpose, when to use, scoping, persistence, and related tools. It provides sufficient context for an agent to invoke correctly without needing return value details.

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 3 applies. The description's key-value pair framing aligns with schema properties and gives examples in the schema itself. The description doesn't add significant meaning beyond what the schema already documents.

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 verb 'Save' and the resource (data for later reuse), and explicitly differentiates from sibling tools by naming recall and forget as paired operations. The scope (across conversation or sessions) adds specificity.

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

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

Provides explicit 'Use when' criteria ('discover something worth carrying forward') and names alternatives (recall, forget). Also gives context on authenticated vs anonymous session persistence, which helps decide when the memory will actually persist.

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

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

The description adds substantial behavioral context beyond the annotations: it mentions cascading through multiple lookup endpoints, graceful degradation if GLEIF or OpenFIGI is unavailable, explicit labeling of identifier sources, and explicit listing of unresolved identifiers. All these align with the readOnlyHint, idempotentHint, and openWorldHint annotations. 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 relatively long but well-structured, starting with example queries and then detailing supported types and behaviors. Every sentence adds value, though some could be tightened. It is front-loaded with the most important usage guidance ('Use FIRST').

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 (multi-source identity resolution, graceful degradation, multiple types) and the absence of an output schema, the description is remarkably complete. It explains what identifiers are returned, how sources are labelled, what happens on failure, and the internal cascading logic. No critical gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the type enum values in detail (e.g., for company: accepts ticker, CIK, ISIN, or company name; ISIN resolves to legal entity via GLEIF). It also clarifies the drug type input and output. This enhances the schema without duplicating it.

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 resolves a user-spoken name to canonical/official identifiers, with specific examples like 'What's the ticker for…' and 'look up the ID for…'. It distinguishes from siblings by implying this is the first step before using other tools that require IDs, and it lists supported types (company, drug) with precise scopes.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', providing strong when-to-use guidance. It also notes that it replaces 2-3 manual lookups. However, it does not explicitly state when not to use this tool (e.g., if you already have an ID) or contrast with siblings like compare_entities or entity_profile, which would be clearer.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks results, and returns a ranked list with score, confidence, and signal density. 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 three sentences with no filler: first sentence states the core action, second explains the probing/ranking mechanism, and third gives a concrete use case and output summary. 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?

There is no output schema, but the description explicitly lists return values (ranked list, score, confidence, signal density). It covers purpose, mechanism, and use case. Parameter details are fully captured by the input schema, so the description is complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, and each parameter (entities, models, _apiKey, context) is well described. The description repeats the 'your brand + N competitors' idea but does not add new parameter-level details beyond what the schema already provides, so it earns the baseline 3.

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

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

The description has a specific verb ('Compare') and resource ('AI visibility' across entities), and clearly states it ranks by score and surfaces most/least recognized. It distinguishes itself from the sibling ai_visibility_check by explicitly referencing it as the underlying probe for each entity, and from generic compare_entities by its AI-presence focus.

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 a clear use case ('competitive AI-marketing audits') with an example, implying when to use it over a single-entity check. However, it does not explicitly state 'use ai_visibility_check for a single entity' or mention exclusions, so it stops short of full when-to-use vs. when-not-to-use guidance.

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

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

Annotations already indicate a read-only, idempotent, open-world operation. The description adds substantial behavioral details: fan-out across two services, graceful degradation with sources_failed, timing caveats for new versions, and the exact summary fields returned. This exceeds the baseline set by 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 comprehensive yet structured, front-loading the core purpose and use case before detailing outputs and edge cases. Every sentence adds value — use cases, return fields, ecosystem scope, and failure behavior — without 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?

For a composite tool with no output schema, the description is exceptionally complete. It lists the return block fields, per-advisory detail, links, alternative versions, ecosystem limitations, and graceful degradation behavior, leaving no major gaps for an agent to select or invoke the tool correctly.

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

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

The input schema already covers 100% of parameter descriptions: 'package' as npm package name and 'version' defaulting to latest. The description reinforces this by linking parameters to output fields (e.g., is_latest, version history), but it does not add significant new semantics 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 explicitly states it is a composite npm package evaluation check, combining deps.dev and bundlephobia data, and clearly names the resources and scope. It is easily distinguished from sibling tools like scan_competitor_ai_presence by focusing on package dependency risk and cost.

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 ('is X safe / popular / small', 'what does adding lodash cost me') and clarifies that non-NPM ecosystems are handled via deps.dev directly. It also notes partial failure modes, giving clear guidance on when results may be 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?

The description reveals substantial implementation details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and a 200K character cap with truncation flagging. This adds context about edge-case behavior and model characteristics that the annotations do not provide.

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 sentences, each earning its place: purpose, usage, pairing, return details, and technical behavior. It is front-loaded with the core action and well-organized, though slightly dense with technical specifics that could arguably be trimmed.

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?

Without an output schema, the description fully explains return values (passages with offsets and similarity scores). It also covers edge cases (truncation with flagging) and technical parameters (embedding model, windowing). Given the read-only annotations, no additional safety or behavior info is needed.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context: 'text you already pulled' clarifies the source, the suggestion about natural-language queries reinforces the query parameter, and 'top-N passages' ties to the limit parameter. It enriches the schema without redundancy.

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

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

The description clearly states a specific verb and resource: 'Semantic search INSIDE a fetched record' and details the output (top-N passages with character offsets and similarity scores). It differentiates from sibling tools by emphasizing it works on already-pulled text, and mentions pairing with ask_pipeworx_grounded.

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

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

Explicitly explains when to use: 'Use when the record is too big to cram into the prompt' and describes the benefit (saves context, returns only relevant passages, verifiable offsets). It also names an alternative workflow with ask_pipeworx_grounded, giving clear guidance on how to combine 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?

Despite annotations being present, the description adds substantial behavioral context: OAuth requirement, phone verification, 10/day SMS cap, webhook HMAC signing, one-time secret return, and auto-disable after 10 failing runs. It goes well beyond the annotations without contradiction.

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

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

The description is long but information-dense, covering purpose, requirements, types, and delivery in a logical flow. Every sentence adds operational detail; a few nested clauses could be trimmed but overall structure is effective.

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

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

With no output schema, the description explicitly mentions return values (subscription id and one-time webhook secret). It covers prerequisites, channel behaviors, limits, and failure handling, making it complete for a moderately complex tool.

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

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

Schema coverage is 100%, but the description enriches each enum type with concrete JSON examples (e.g., sec_8k items, polymarket_edge topic, fred_series series_id) and elaborates on delivery object fields including verification and webhook signing. This exceeds the baseline for high schema coverage.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream' and states 'Returns the new subscription id,' clearly identifying a specific verb, resource, and scope. It effectively distinguishes this from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides explicit prerequisites (Pipeworx OAuth account) and enumerates supported types with usage examples, implying when to use. It doesn't explicitly point to alternatives or exclusions, but the context makes the tool's role clear relative to 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?

Even though annotations already declare readOnlyHint and openWorldHint, the description adds valuable behavioral context: it explains the output format (category-bucketed example questions), the source (live catalog), and how omitting vs passing the topic parameter changes the result. It also mentions the exact categories, providing a mental model of the tool's behavior beyond the annotations.

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

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

The description is longer than average but every sentence earns its place: it covers example queries, output structure, parameter behavior, and usage priority. It is front-loaded with user-facing intents and well-structured, though a minor trimming of the category list could improve skimmability without losing meaning.

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

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

Given the tool's simplicity (1 optional param, no output schema, no nested objects), the description fully covers the purpose, output, parameter semantics, and usage context. It even names the meta-tools the user can learn about, making it complete for an onboarding tool. No gaps remain.

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

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

The schema already describes the `topic` parameter with allowed values, so the baseline is 3. The description adds value by giving concrete examples ('finance', 'pharma', 'betting') and explaining that omission yields a cross-category spread, which enriches the schema's plain list of allowed values. The description goes slightly beyond the schema without being redundant.

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 is the onboarding entry point for learning what to ask Pipeworx, returns category-bucketed example questions with exact tool and argument shapes, and distinguishes itself from meta-tools like ask_pipeworx and entity_profile. It uses specific verbs like 'returns' and 'Call' with a concrete resource (live catalog of tools).

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

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

The description provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the no-argument vs. topic-filtered calling patterns, giving clear direction for alternative 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 beyond annotations by disclosing key behavioral traits: ownership enforcement, soft-deactivate instead of hard delete, and preservation of historical events. This adds valuable context beyond the annotated hints, making the tool's behavior clear.

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

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

The description is extremely concise at two sentences, with the primary action front-loaded. Every sentence provides useful information without redundancy.

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

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

The tool is simple (one parameter, no output schema), and the description sufficiently covers purpose, behavior, and consequences. It mentions the related 'recent_alerts' tool for historical flexibility, making it complete for the tool's complexity.

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

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

The schema already provides 100% coverage for the 'id' parameter, including it being a UUID returned by subscribe. The description adds the ownership constraint (only your own subscriptions), which gives additional meaning about valid values for the 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 states a clear action ('Cancel a subscription') on a specific resource ('by id'), and the title reinforces the purpose. It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by describing the cancellation behavior.

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 that this tool cancels a subscription and that historical events remain available via 'recent_alerts', implying when this tool is appropriate. It doesn't explicitly mention alternatives, but the reference to 'recent_alerts' offers a contrast that helps guide usage.

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

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

Annotations already define read-only and non-destructive behavior, but the description adds critical behavioral context: it explains the verdict taxonomy, the meaning of could_not_verify (including the verification_error object and its distinction from unsupported), and the internal pipeline (fast path vs. grounded). This goes far beyond what annotations provide and guards against misinterpretation of results.

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 many, but every section adds value: trigger phrases, usage, routing, output, and edge-case warnings. It is front-loaded with user intents and clearly structured. A slight deduction because the list of synonyms is somewhat redundant, but the density is appropriate for the tool's complexity.

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

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

Given the tool has only 2 parameters and no output schema, the description compensates thoroughly by detailing return values (verdict, cited value, reasoning), explaining the internal routing and evidence handling, and clarifying ambiguous outcomes. It is complete enough for an agent to correctly invoke the tool and interpret results without needing additional info.

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

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

The input schema already provides 100% coverage for both parameters, with clear descriptions and examples for claim and tolerance_pct. The tool description does not add additional parameter-level detail beyond what the schema states, so the baseline of 3 applies. It briefly mentions "percent-delta math" but does not elaborate on the tolerance_pct parameter itself.

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 names the tool's function as natural-language claim verification/fact-checking, with concrete trigger phrases ("Is it true that…", "fact check", "verify the claim that…"). It also distinguishes from general Q&A tools by stating it returns a verdict and is a consolidated replacement for multi-step calls. This clearly identifies a unique purpose beyond the title.

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 says "Use whenever the agent needs to check whether something a user said is factually correct," giving a direct use condition. It further segments claim types (company-financial vs. other) and explains how each is routed, effectively telling when this tool is the right choice and that it displaces several sequential steps. This is explicit usage guidance without ambiguity.

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