Market Spread

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond these annotations: the default model (Workers AI Llama-3.3-70b) is free, while using Anthropic requires a BYO key and direct payment. It also discloses the return structure (per-model {score, confidence, signals, raw_response} + combined view), which is useful for setting expectations. 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 two sentences with no redundancy. It front-loads the core action, then provides default behavior, output format, and use cases. Every sentence contributes new information, making it highly efficient and 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 moderate complexity (4 params, 1 required) and the absence of an output schema, the description is fairly complete. It states the return format (per-model score, confidence, signals, raw_response + combined view) and provides relevant use cases. Minor gaps exist, such as not detailing the 'combined view' or 'signals', but this is acceptable given the concise format.

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

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

Schema coverage is 100%, so the parameters are well documented. The description adds meaningful semantics beyond the schema: it clarifies cost implications of the _apiKey parameter ('you pay Anthropic directly') and reinforces the default model behavior for the 'models' parameter. While the schema already explains the API key purpose, the cost disclosure is an extra dimension that elevates the score above the baseline.

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

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

The description clearly states the tool's function: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' The verb 'probe' is specific, the resource (LLMs) is identified, and the output (visibility score) is explicit. It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on direct LLM probing with a 0-100 score.

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 offers clear context for when to use the tool: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains default model behavior and optional Anthropic probing. However, it does not explicitly state alternatives or when not to use it, so it lacks the exclusionary guidance that would merit 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 establish the tool as read-only, open-world, and idempotent, and the description aligns with that. It adds context about the routing mechanism, fast execution, tier availability, and the return format with stable pipeworx:// URIs. However, it does not mention error handling or rate limits, which would be useful but are not critical for a read-only tool.

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

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

The description is lengthy but information-dense, front-loading the 'PREFER OVER WEB SEARCH' directive, listing scope, providing examples, and explaining alternatives. Every sentence contributes value, though the listing of trigger phrases could be slightly more concise 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 broad routing complexity and the lack of an output schema, the description covers the core function, return format, use-case boundaries, and escalation paths. It is sufficiently complete for an agent to decide when and how to invoke the tool, including examples and domain coverage.

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?

All six schema properties are aliases for the single 'question' parameter and have full description coverage. The tool description adds semantic guidance by suggesting trigger phrases like 'what is', 'look up', and providing example questions, helping the agent understand how to formulate effective 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?

The description opens with 'PREFER OVER WEB SEARCH' and clearly states it routes questions to 5,529 tools and returns structured answers with citation URIs. It explicitly lists data domains and provides multiple examples, making the tool's purpose unmistakable and distinct from web search and sibling tools.

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

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

It provides explicit use cases: any factual question, even if web search could answer. It distinguishes when to step up to ask_pipeworx_grounded for grounded answers or deep_research for broad multi-part questions, and addresses breaking-news scenarios. This gives clear when-to-use and 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 read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: the tool is an experimental edge that may switch routing behavior when a candidate is under test, currently matches ask_pipeworx exactly, and falls back to nothing (fully functional). This goes beyond the annotations and clarifies the live 'candidate' aspect.

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

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

The description is concise yet information-dense, divided into four clear sentences: purpose, current status, usage instruction, and a clarification about fallback. Each sentence earns its place, and key details (beta, identical router, no active candidate, experimental) are front-loaded.

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

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

For a tool with no output schema and a relatively simple parameter set, the description is complete: it explains what the tool does, its current state (no candidate active), how to use it (like ask_pipeworx), and its relation to the stable router. It also notes the response shape matches ask_pipeworx, so users know what to expect.

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 covers 100% of parameters with detailed descriptions, including the aliases for 'question'. The description adds no extra parameter-level detail, but it does state 'same arguments' as ask_pipeworx, which is a minimal addition. The schema already does the heavy lifting, so 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 clearly identifies the tool as a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. This specific verb+resource combination distinguishes it from siblings like ask_pipeworx and ask_pipeworx_grounded, especially by highlighting the experimental routing improvements.

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

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

The description explicitly states when to use the tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that results are compared to the stable router. While it doesn't explicitly discuss alternatives or exclusions (e.g., ask_pipeworx_grounded), the usage context is clear and practical.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description reveals significant behavioral details: it returns structured responses with evidence and confidence, provides an explicit refusal mechanism with a defined set of refusal_reason values, and strictly limits extraction to tool result content (no invention). It also discloses the extra LLM call cost. This goes far beyond what annotations convey and adds critical runtime expectations.

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

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

Although the description is longer than average, every sentence earns its place: summary, routing mechanism, extraction method, return shape (success and failure), specific use cases, and cost trade-off. It is front-loaded with the core purpose and structured to lead the agent through what it does and when to use it. No filler or tautology.

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 has no output schema, but the description fully compensates by explicitly enumerating the success return fields and the refusal conditions. It also covers usage context, cost implications, and the distinction from ask_pipeworx. Given the tool's moderate complexity and rich behavioral surface, this description is sufficiently complete for an agent to select and invoke it correctly.

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

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

The input schema is fully self-descriptive: all 6 parameters are aliases for 'question' and are individually described, giving 100% schema_description_coverage. The description does not add parameter-level meaning beyond what the schema already provides, so the baseline score of 3 is appropriate. No additional syntax or format details are 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 a specific, action-oriented summary: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly states the tool extracts an answer from tool results, and explicitly distinguishes itself from the sibling ask_pipeworx by noting 'Same routing as ask_pipeworx' but with grounded extraction and explicit refusals. This is a precise verb+resource+mode statement that differentiates it from related 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?

Usage guidance is explicit and actionable: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts...' It also names the alternative tool and the trade-off: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This clearly tells the agent when to choose this tool over its primary 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?

Annotations already declare readOnly/openWorld/idempotent/non-destructive, but the description adds extensive behavioral detail: it discloses fan-out logic, resolver contracts with confidence scoring, parent-event extraction, news fallback handling, blocking statuses for low-confidence/closed markets, illiquid-spread flags, and cancellation-rule interpretation. It goes far beyond annotations to give agents a precise model of what the tool does internally and how to interpret outputs.

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, using clear section headers (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK) and front-loading the primary purpose. Every major section adds necessary operational context for a complex tool with no output schema. It is not overly repetitive, though some sentences are dense and could potentially 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?

With no output schema, the description carries the full burden of explaining response shapes and edge cases. It thoroughly specifies result fields, market_match_confidence levels, blocking statuses, news fallback flags, and resolution-rule risks. It also includes concrete fan-out examples and warnings about safety and illiquidity. This is as complete as a tool description can be, giving an agent everything needed to correctly understand 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 coverage is 100% with descriptions for all three parameters. The description adds meaningful examples for 'market' (slug, URL, question text), explains the trade-offs of 'include_raw' (response size, use cases for raw data), and implies behavior of 'depth' via fan-out scope. It contributes value beyond the schema by connecting parameters to downstream resolver behavior, though 'depth' is not deeply explained in prose.

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 begins with a specific verb+resource+approach: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states the accepted inputs (market slug, URL, or question text) and distinguishes the tool's purpose from sibling research tools by providing use-case examples ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). This is unambiguous and actionable.

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

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

The description explicitly states when to use the tool: 'Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'.' It also provides concrete usage warnings (e.g., 'Check this before sizing sports/esports/event-occurrence bets') and examples of parameter combinations. However, it does not explicitly mention what to use instead for alternative scenarios, so it slightly misses a full 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?

Beyond the readOnly/idempotent annotations, the description discloses specific data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), return behavior (sorted by primary metric), and output details (paired data + citation URIs). It also handles edge cases like off-calendar fiscal years, providing rich behavioral context not evident from 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 dense but every sentence earns its place: trigger phrases, explicit preference guidance, type-specific details, sorting behavior, and citation output. It is front-loaded with the most critical information (what it does and when to prefer it), and despite length, it is structured and free of fluff.

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

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

Given the tool's moderate complexity (two types, no output schema), the description covers all essential aspects: purpose, usage context, data sources, result ordering, and return format. It effectively compensates for the lack of an output schema by stating that paired data and citation URIs are returned, making it fully self-contained for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics by explaining what each 'type' value does (pulls 10-K vs FAERS data), which clarifies the expected entity types and the nature of the comparison. It reinforces the schema's parameter descriptions without repeating them verbatim, 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 clearly states it performs side-by-side comparison of 2–5 companies or drugs in one call, with specific verbs like 'compare' and 'rank'. It distinguishes from siblings by explicitly saying 'ALWAYS PREFER over sequential single-pack lookups' and handles two entity types (company/drug) with distinct data sources.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also gives trigger phrases ('X vs Y', 'which is bigger') and explains the tool's advantage ('Replaces 8–15 sequential lookups'). This makes the intended usage clear without needing to consider alternatives.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds significant behavioral context beyond this: parallel venue queries, error venues reported as { reachable: false }, never failing the call, return shape details, divergence only computed with Jaccard overlap, and honest caveat that high spread does not mean real arbitrage.

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 it is well-structured, front-loaded with the core purpose, and uses clear sections (landscape scan, return shape, HONESTY caveat, alternative). Every sentence adds value, though it could be slightly more concise for faster scanning.

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 takes on full responsibility for explaining return values and behavior. It covers the return shape, failure handling, divergence logic, and important caveats about interpreting spreads. This is complete enough 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?

The schema has 100% coverage for both parameters, so the baseline is 3. The description does not add much parameter-specific detail beyond the schema; it indirectly references per-venue top matches and the topic concept, but the schema already fully documents `topic` and `per_venue`. No additional semantic value beyond what the schema provides.

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

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

The description states a specific verb and resource: it is a 'Cross-venue prediction-market LANDSCAPE scanner' that 'show[s] how 5 venues are pricing [a topic] side by side and flag[s] divergence.' It clearly distinguishes itself from executable arbitrage tools by naming the alternative and explicitly stating it is 'NOT an executable-arb tool.'

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

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

The description provides explicit usage context: use for scanning one topic across multiple venues to find where to look for mispricing. It also states when not to use it ('NOT an executable-arb tool') and names the alternative (`polymarket_arbitrage` pack) for executable arbitrage requiring order-book depth.

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

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

Beyond the readOnlyHint=true annotation, the description discloses rich behavioral context: requires account (free/paid tiers), detailed latency (15-90s), parallel tool routing, gap[] handling, contradictions[], hop fields, excerpting behavior, and citation resolvability. This far exceeds what annotations provide and accurately characterizes the tool's behavior.

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

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

The description is long but information-dense; every sentence adds substantive operational detail (account requirements, routing, gaps, citations, times). It front-loads the account requirement and core purpose, which are critical for tool selection. Some redundancy exists (e.g., depth details repeated in schema), and it could be tightened slightly, but it earns its length given 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?

The description fully compensates for the lack of an output schema by spelling out the findings packet structure (verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[]). It covers edge cases like unresolved gaps, citation resolvability, and performance expectations, making the tool's behavior predictable for the agent.

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

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

Schema covers both parameters 100%, including enum meanings. The description adds extra semantic nuance by explaining how the depth values map to hops (quick=single hop, standard=gap recovery, thorough=full iterative hop) and by elaborating on the question parameter's scope ('decomposition is the point'). This adds meaning 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 states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources in ONE call.' It explicitly contrasts with open-web search and sibling tools (ask_pipeworx), making its unique scope and output 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?

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and explicitly says 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx.' Also covers account requirements and alternatives, giving the agent clear decision rules.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is fully covered. The description adds that the tool returns top-N results with names, descriptions, and full input schemas including curated examples, and that each result is ready to call directly without a second schema lookup—useful behavioral detail 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 front-loaded with the main purpose and returns a compact set of high-value details, but the domain list is long (17 items) and the phrasing 'Returns the top-N most relevant tools...' could be tightened. Overall it's appropriately sized for the tool's function, earning a 4 rather than 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 simple, read-only discovery tool with no output schema, this description covers the essential ground: what it does, when to use it, what it returns, and how results are structured. The only minor omission is what happens when no tools match, but that's low-stakes given the intended use case.

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

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

Schema coverage is 100% with descriptions for all six parameters, including multiple aliases for query. The description only loosely maps to the query parameter ('describing the data or task') and the limit ('top-N'), adding no new meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

Description opens with a specific verb+resource ('Find tools by describing the data or task') and enumerates a broad range of domains (SEC filings, FDA drugs, etc.), making its discovery function explicit. It distinguishes itself from sibling research tools by stating it returns top-N tools with full schemas, ready to call directly, and by positioning itself as the 'first' step when the option set 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?

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for...' and instructs 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It lacks a direct 'when not to use' statement or named alternative tools, but the 'not just one answer' phrase implies you should use direct tools for a single answer.

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

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

Annotations already declare read-only and idempotent behavior, but the description adds rich behavioral detail: it fans out across multiple sources, returns specific fields with sorted fundamentals, soft-fails patents due to API sunset, and uses a GDELT→GNews fallback. It also discloses the input limitation (names not supported). This goes well 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 long but well-structured, front-loading example queries and a clear preference statement, then listing return components and input constraints. Each sentence provides distinct information, though the many examples and nested clauses make it somewhat dense. It earns its length but could be slightly tighter.

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 thoroughly explains return values (CIK, company name, recent filings with URIs, fundamentals sorted by period, patents, news fallback, LEI) and input constraints. This gives the agent a complete mental model of what the tool does and what to expect, fully compensating for the lack of output schema.

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

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

Schema coverage is 100% and the schema already fully describes both parameters (type with enum, and value with ticker/CIK and the name-not-supported note). The description repeats this information but adds no new parameter-level semantics, so 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 produces a full cross-source profile of a US public company, with specific examples like 'Tell me about X' and 'research Acme'. It distinguishes itself from siblings by describing the one-call holistic aggregation and explicitly noting support for ticker/CIK but not names, which separates it from resolve_entity.

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

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

The description gives explicit when-to-use guidance: whenever a user asks for a holistic company view, and explicitly says to prefer it over chaining single-pack lookups. It also provides a clear exclusion: if you only have a name, use resolve_entity first. This is strong contextual direction.

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 destructiveHint=true and idempotentHint=true, so the description's 'Delete' aligns. The description adds the context of clearing sensitive data but does not disclose additional behaviors like return values or behavior on non-existent keys, leaving a moderate gap despite annotation coverage.

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, starting with the action and then providing usage guidance. Every sentence adds value: what it does, when to use, and related tools. No fluff.

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

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

For a simple one-parameter destructive tool with annotations covering safety, the description covers the operation, usage timing, and relationship to siblings. It does not mention return behavior, but given the unchanged schema and annotations, it is adequately complete for invocation.

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

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

The input schema provides 100% coverage for the single 'key' parameter with the description 'Memory key to delete,' matching the tool description's 'by key.' The description adds no further semantic details, 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 function: 'Delete a previously stored memory by key,' specifying the verb (delete), resource (memory), and operand (key). It differentiates from sibling tools by focusing on deletion, while 'remember' and 'recall' are for storing and retrieving.

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

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

Provides explicit usage conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Mentions related tools 'remember' and 'recall' via 'Pair with,' indicating a memory workflow, though it does not explicitly list when-not-to-use exclusions.

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

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

Given annotations already declare the operation safe (readOnlyHint=true, destructiveHint=false), the description adds valuable context: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This process detail helps the agent predict behavior beyond the safety 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 three sentences, each serving a distinct purpose: purpose, process/output, and use cases. It is front-loaded with the main function and contains no redundant 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 read-only, idempotent tool with comprehensive annotations and full schema coverage, the description explains the input, process, output format, and typical use scenarios. The lack of an output schema is compensated by describing the output as a single text blob ready for deployment.

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 'url' and 'max_links' documented in the schema. The description does not add parameter-specific detail beyond what the schema already provides, so the baseline score of 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 function: generating a production-ready llms.txt file for any URL. It specifies the verb 'Generate', the resource (llms.txt file), and the unique scope ('any URL'), distinguishing it from sibling tools like 'ai_visibility_check' or 'scan_competitor_ai_presence' which target different aspects of AI visibility.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting llms.txt for a project, or auditing a competitor's AI visibility. However, it does not explicitly state when not to use it or name alternative tools, leaving a small gap in exclusion guidance.

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

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

Beyond annotations which declare read-only, idempotent, and non-destructive behavior, the description adds meaningful context: it lists active subscriptions by default, scopes to the caller's subscriptions, and enumerates return fields.

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

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

Two sentences are concise and front-loaded with the operation. They include the return fields and usage guidance without any 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?

For a simple tool with one optional parameter, rich annotations, and an explicit list of return fields, the description covers purpose, usage, and behavior completely.

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 description for include_inactive already explains its meaning and default (false), and schema coverage is 100%. The description does not add parameter-level details, so baseline 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields (id, type, params, etc.), distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

The description gives explicit use cases: review what you're monitoring before adding more and find an id to cancel. It does not name alternative tools, but the context implies this is the reviewing tool for subscription management.

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 are all false, providing no safety hints, so the description carries the full burden. It discloses significant behavioral traits: filing without an account returns a claim_token, token reuse for follow-up, rate limiting to 5 per identifier per day, non-quota consumption, and daily digest review. These go well beyond the annotations and give the agent a complete behavioral model.

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

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

The description is a dense paragraph but every sentence adds value, and the opening line is front-loaded with purpose. It lacks visual structure (bullets) and is longer than strictly necessary, but it is not verbose in a wasteful way. It balances completeness with clarity, earning a score above average.

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 (4 parameters, nested context object, no output schema), the description is fully complete. It explains the return token mechanism, rate limits, scope boundaries, and how to structure feedback. Combined with a 100%-covered schema, the agent has all necessary context to invoke this 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 coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: it instructs not to paste the end-user's prompt, clarifies that claim_token should be passed with no other arguments, and explains how to reference Pipeworx tools/packs. This elevates it above the baseline but still relies heavily on the schema for parameter details.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from sibling tools by scoping exclusively to Pipeworx-served tools and explicitly excluding other MCP servers. This fully clarifies the tool's purpose and differentiates it from alternatives.

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also states when not to use it (for tools from other MCP servers) and explains correct usage of the claim_token. This is exemplary usage guidance with clear exclusions.

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

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

Beyond the readOnly/idempotent annotations, the description discloses that the data is self-aggregating from CF analytics-engine, contains no PII, and is cached for 5min-1h depending on the window. This adds meaningful behavioral context about freshness, privacy, and data provenance.

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 front-loaded: the main function is stated in the first sentence, followed by three clearly numbered use cases and a concise data/caching note. Every sentence adds value and nothing is redundant or verbose.

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 read-only trend tool with one optional parameter, the description fully covers what is returned (top tools, top packs, total call volume, pack/tool/count), why it's useful, how it's derived, privacy implications, and caching behavior. The lack of an output schema is compensated by the explicit return data shape.

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

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

Schema description coverage is 100% for the single optional 'window' parameter, and the schema already explains the semantics of 24h, 7d, and 30d. The description repeats the window options but does not add further parameter-level meaning beyond what the schema provides, so the 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 uses a specific verb ('Returns') with a clear resource (top tools, top packs, total call volume over recent windows), and immediately distinguishes it from sibling tools by focusing on aggregate trending usage across agents. It clearly conveys the tool's unique role as a popularity/consensus signal.

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 lists three concrete use cases: discovering hot data sources, confirming canonical tool choice, and checking alignment with other agents' needs. It doesn't name alternatives or exclusions, but the context is strong and actionable enough for an agent to decide when to invoke 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 only declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds substantial behavioral detail beyond that: threshold for partition deviations (>3pp), Jaccard similarity anchor (≥0.30), placeholder filter (20%), and the fill check (theoretical vs realizable edge, 'do not trade it' when realizable ≤0). It also discloses that the tool internally calls arbitrage.fill_check against live CLOB depth. 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 dense and lengthy, but it is logically structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the primary purpose and mode selection. Every sentence conveys useful information, so while it's not perfectly concise, it earns a 4 for effective organization and 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?

Given the tool's complexity (three modes, multiple checks, fill risk), the description is remarkably complete. It describes the response structure (opportunities[] with fields, partition_check fields, skipped_low_similarity count) and the FILL CHECK output. With no output schema present, the description carries the full burden and meets it well.

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

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

Even though schema coverage is 100%, the description greatly enriches parameter meaning. For `event`, it explains that the tool 'walks child markets, checks date-axis / threshold-axis ordering AND computes the partition_check.' For `topic`, it details the cross-event search and flattening process. It also gives concrete example slugs and notes that full URLs are accepted. This goes far beyond the schema's one-line descriptions.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly identifies the tool's function and distinguishes among three modes (trending_scan, event, topic), with concrete examples and recommendations. This fully differentiates it from siblings like polymarket_fill_risk.

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

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

Explicit usage guidance is provided: 'Call with NO args for a trending_scan... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' It also states when to prefer one mode over another (event recommended for a specific market) and names an alternative tool: 'For custom sizing use polymarket_fill_risk.' This is exactly the kind of when-to-use vs. alternatives guidance that earns 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?

The description goes well beyond the annotations (readOnlyHint, idempotentHint) to reveal internal behavior: the exact model families, per-sport α values, placeholder-slug filtering, partition overround correction, and the reason partition arbs return kelly_fraction_half=0 at the parent level. It also discloses caching at the KV level for 1 hour and the inclusion of diagnostic funnel counters. No contradiction with annotations exists.

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

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

The description is a dense, continuous paragraph using all-caps and parentheses, making it hard to scan. It is front-loaded with purpose but quickly dives into intricate details like per-sport α and placeholder-slug filters. While every sentence carries information, the lack of bullets or sections reduces readability for an agent needing rapid comprehension.

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

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

Given the tool's complexity and lack of an output schema, the description is exceptionally complete. It explains the response top-level fields (by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity), and even the 24h-move warning. It also covers caching, Fed caveats, and filter behaviors, ensuring an agent can invoke the tool and interpret results correctly.

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

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

Although the schema has 100% description coverage, the tool description adds meaningful context for the tradeable-edge knobs: min_liquidity/max_spread_pp are explained as drop filters for unrealizable edges, and min_partition_leg_kelly is clarified as applying to per-leg Kelly since parent-level kelly_fraction_half=0. It also relates slippage_pp to Polymarket bid/ask behavior. This extra interplay is not in the schema.

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

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

The description begins with a precise statement: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It explicitly targets the 'what should I bet on today' use case and distinguishes itself from sibling tools by focusing on this discovery task. The three model families and response segments are clearly enumerated, leaving no ambiguity about the tool's 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?

The description provides clear guidance on when to use the tool ('Built for "what should I bet on today"') and explains the tradeable-edge knobs, e.g., min_liquidity and max_spread_pp 'drop opportunities where edge isn't realizable.' It also includes a caveat about Fed bet signals being unreliable without paid data. However, it does not explicitly name alternative sibling tools or state when not to use this tool, so it stops short of full exclusion guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description reveals critical behavioral details: snapshots are written on cache-miss, gaps mean no scan that day, history is bounded by a 60-day TTL, decay is computed from daily closes, and the response structure includes expired opportunities. This substantially exceeds the annotation baseline.

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

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

The description is long but well-structured with clear labels (Args, RESPONSE, LIMITS). It packs extensive information without redundancy, though it could be slightly tightened. Each sentence adds meaningful detail.

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

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

With no output schema, the description fully documents the return format: tracked[], expired[], and snapshot_dates[] with their fields. It also covers limitations (TTL, start time, daily vs intraday), 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?

Schema coverage is 100%, so the baseline is 3. The description adds default and max values and clarifies that 'window' refers to snapshot families, but this is marginal value beyond the schema. No additional syntax or format details are 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 clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. It uses specific verbs ('tracks', 'answers') and distinguishes from sibling tools like polymarket_edges by focusing on historical trend analysis 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 clear context on when to use this tool — to differentiate fresh vs. old wide edges before trading — and explains the implications of edge age. It does not explicitly compare with alternative tools or state exclusions, but the intended use case is unambiguous.

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 already indicating a read-only, idempotent, non-destructive operation, the description adds substantial behavioral detail: it walks the order book ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage, etc.), explains the verdict values, describes how size_usd is interpreted in both modes, and warns about partial basket fills creating directional risk. No contradiction with annotations.

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

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

The description is dense but well-structured, with clear section labels (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Every sentence contributes actionable information, from mode-specific parameters to returned fields and risk warnings. It front-loads the core purpose and then efficiently elaborates without redundancy.

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

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

Given there is no output schema, the description fully compensates by enumerating the return values for both single-market and basket modes, including verdict values and risk metrics like thin_legs and forced_directional_risk. It also provides the rationale for using the tool, covering 'why' as well as 'what' and 'how,' making it complete for real-world usage.

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

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

While the input schema covers 100% of parameters with descriptions, the tool description goes further by explaining the dual-mode semantics: for market it specifies that size_usd is 'max spend on buys, target proceeds on sells,' and for basket it interprets size_usd as settlement notional S (shares per leg). It also details the side parameter defaults and the auto-selection logic, adding meaning beyond the schema.

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

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

The description opens with a clear, specific statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes itself from sibling tools by focusing on fill risk/order-book depth rather than just arbitrage detection or edge calculation, and it explicitly references when to use it (before acting on arb signals).

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also clearly differentiates single-market vs basket modes and explains the auto behavior for basket side, leaving no ambiguity about when to invoke the tool.

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

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

Annotations already declare readOnlyHint/openWorldHint/idempotentHint, and the description adds extensive behavioral context: compatibility_warning conditions, temporal_alignment with aligned:false meaning meaningless spreads, skipped_cross_type/subtype counters, and the caveat that pre-mapped ≠ tradeable. This goes far beyond the annotations and discloses the tool's limitations honestly.

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 logically structured into purpose, modes, response, safety fields, and a closing caveat. Every section earns its place given the tool's complexity; it could benefit from markdown bullets, but the flow is coherent and free of 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?

Despite no output schema, the description thoroughly documents the response shape (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped_cross_type/subtype) and covers nuanced edge cases like non-equivalent bet shapes and temporal misalignment. For a complex cross-venue analysis tool, this is 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%, so the baseline is 3. The description enhances this by explaining the conceptual distinction between topic mode (pre-mapped auto-fetch) and explicit mode (custom pairings overriding the mapped side), adding context like 'auto-fetch the matching event' and 'Overrides the topic-mapped side,' which the schema descriptions do not convey.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly identifying the operation and the two resources involved. It distinguishes itself from siblings like venue_quotes (single-venue) and polymarket_edges (Polymarket-specific) by explaining two modes (topic shortcuts vs explicit tickers) and the response summary.

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

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

The description clearly explains when to use each mode (`topic` for pre-mapped shortcuts vs explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings) and warns that pre-mapped topics often return compatibility_warning, implying they are not always tradeable. However, it does not explicitly compare against sibling tools for exclusion scenarios.

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

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

Annotations already declare readOnly, non-destructive, and idempotent. The description adds valuable context about scoping to the agent's identifier and the behavior of omitting the key, going 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 the primary action, followed by usage, scoping, and pairing. Every sentence contributes value with no redundancy.

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

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

For a simple tool with complete annotations and schema, the description fully covers purpose, usage, scope, and related tools. No missing critical information.

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

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

Schema coverage is 100% and the key parameter is described. The description reinforces it with examples (ticker, address) and clarifies the omit-to-list behavior, adding meaning beyond the schema.

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

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

The description clearly states the tool retrieves saved values or lists keys, with a specific verb and resource. It explicitly differentiates from sibling tools remember and forget, mentioning the pairing.

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 clear context on when to use the tool (look up previously stored context) and names the paired tools remember and forget. However, it does not explicitly state when not to use it or compare with other siblings in detail.

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

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

Description states 'Set mark_read:true to flag returned events read' which is a state-changing operation, directly contradicting the annotation readOnlyHint:true. This is a clear contradiction and warrants the lowest score.

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

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

The description is compact, front-loads the core action, and every sentence adds meaningful detail without fluff. It efficiently conveys filters, return payload, and alternative access.

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 covers return format (source, citation_uri, raw payload), filtering options, mark_read behavior, polling, and an alternative endpoint—making it highly complete for an agent to understand the tool's behavior.

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

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

Schema covers all 5 params, but description adds value by giving a filter example ('sec_8k'), explaining the effect of mark_read on future calls, and clarifying polling suitability—going beyond the schema descriptions.

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

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

Description clearly states 'Pull fired events from your subscription feed' with a specific verb and resource, and distinguishes itself from siblings like list_subscriptions which list subscriptions, not events. The purpose is unambiguous.

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

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

Provides explicit usage guidance by noting 'Polls work fine' and offering an alternative access method via HTTP endpoint for scripts/dashboards. This gives clear direction on when to use the tool vs. the alternative.

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

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

Beyond the readOnly/idempotent annotations, the description discloses fan-out behavior, GDELT→GNews fallback conditions, USPTO soft-fail due to API sunset, accepted date formats, and the return structure (changes[], total_changes, citation URIs). This is rich, non-obvious behavioral context.

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

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

The description is longer than necessary but every sentence carries useful information. It opens with query examples (slightly delayed purpose statement) but remains well-structured and free of fluff. Slightly verbose yet highly informative.

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

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

Given no output schema, the description fully describes return shape (changes[] grouped by source, total_changes, pipeworx:// URIs), source fallbacks, and parameter nuances. It also references the PatentsView sunset, making the tool's current limitations explicit.

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%, but the description adds value by explaining the 'since' relative shorthand with examples ('7d', '30d', '3m', '1y') and recommends '30d' or '1m' for typical monitoring. It also clarifies the output grouping by source, which maps to parameter usage.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months' and explicitly contrasts with entity_profile. It lists specific sources (SEC EDGAR, GDELT/GNews, USPTO) and gives query examples, leaving no ambiguity about purpose.

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

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

It provides explicit query phrasings ('What's new with X', 'latest on Y') and an explicit alternative: 'Use entity_profile instead when you want the static profile...'. This tells the agent exactly when to use this tool versus a 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?

Adds behavioral context beyond annotations, including persistence differences (authenticated persistent vs. anonymous 24-hour retention), scoping by identifier, and the key-value storage model. Does not contradict the readOnlyHint=false or idempotentHint=true 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 but comprehensive, front-loading the primary purpose and including all necessary usage context. Every sentence contributes 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 simple two-parameter tool with a full schema and useful annotations, the description covers usage scenarios, persistence behavior, and sibling relationships. No output schema is needed, and the description is complete for effective tool selection and invocation.

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

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

Schema coverage is 100%, providing clear descriptions for key and value. The description adds semantic nuance by explaining that keys are scoped by identifier and offering example keys and value types, enriching the meaning beyond the schema alone.

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

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

The description clearly states the tool's function with a specific verb ('save') and resource ('data the agent will need to reuse later'). It distinguishes itself from siblings by mentioning cross-session persistence and key-value scoping, and explicitly contrasts with recall and forget.

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

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

Provides explicit when-to-use guidance with concrete examples (resolved ticker, target address, user preference, research subject). It also states the relationship to recall and forget, giving clear context for when this tool is the right choice.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses key behaviors: identifiers are source-labelled, unresolved identifiers are explicitly listed, enrichment degrades gracefully if GLEIF/OpenFIGI are unavailable, and each call cascades through multiple lookup endpoints. This gives the agent important expectations about outputs and failure modes.

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

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

The description is front-loaded with the core purpose and usage guidance, and all sentences contribute valuable information. However, it is quite dense with parenthetical details about sources and enrichment, making it longer than necessary for a quick scan.

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 compensates by enumerating exactly what identifiers are returned per type, how unresolved identifiers are represented, and how enrichment degrades gracefully. For a multi-lookup tool, this is a complete picture that prepares the agent for all expected outcomes.

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 only provides basic enum/type info, but the description adds rich meaning: for type=company it explains the cross-source identity spine (CIK/ticker/LEI/FIGI) and input forms; for type=drug it describes the RxCUI/ingredient/brand return and accepted names. This significantly enhances understanding beyond the schema.

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

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

The description clearly defines the tool as resolving user-spoken names to canonical/official identifiers, with concrete examples and supported types (company, drug). It positions itself as the entry-point for name-to-ID lookups, which distinguishes it from sibling tools like entity_profile or compare_entities.

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 FIRST whenever you have a name but need an ID." It also notes that using this tool replaces 2-3 manual lookups, giving the agent a strong signal for when to invoke it. This is clear and actionable.

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

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

Annotations already state readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds value beyond these by disclosing the probe-and-rank behavior, the use of ai_visibility_check, and the returned fields (score, confidence, signal density). It doesn't cover failure modes or API-key behavior, but the schema handles that.

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

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

The description is three sentences, front-loaded with the main purpose, and every sentence serves a function: state the behavior, provide an example use case, and summarize the return structure. No filler or 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?

With no output schema, the description adequately states the ranked list output and its fields. It doesn't mention model-selection behavior or edge cases, but the schema covers those. For this complexity level, the description is nearly complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds limited parameter context (e.g., 'your brand + N competitors' reflecting the entities parameter) but mostly relies on schema descriptions for models, _apiKey, context, and entities.

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 and resource: 'Compare AI visibility across multiple entities side-by-side' and clearly states it probes entities with ai_visibility_check, ranks by score, and surfaces most/least recognized. This distinguishes it from the singular ai_visibility_check sibling tool and from generic compare_entities by emphasizing competitive AI-marketing audits.

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 clear context and a concrete example use case: 'Useful for competitive AI-marketing audits: "does Claude know about us as well as our competitors?"'. It implies when to use it (multi-entity comparison) but does not explicitly mention when not to use or name alternative tools.

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

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

Beyond the read-only/idempotent annotations, the description discloses partial failure behavior, the 5-30s first-measurement latency from bundlephobia, and the sources_failed field. It also explains the composite nature and ecosystem scope, adding meaningful context without contradicting annotations.

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

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

The description is somewhat long but every sentence earns its place: composite purpose, usage triggers, return fields, ecosystem scope, and failure mode. It is front-loaded with the core purpose and structured logically, though it could be slightly tightened.

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 enumerates the summary block fields, per-advisory detail, links, and alternative versions, plus the ecosystem scope and latency/degradation behavior. This is sufficiently complete for an agent to invoke the tool correctly and interpret the result.

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

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

The input schema already fully describes both parameters (package name with scoped packages accepted, version with default to latest). The description does not add additional parameter-level details, so it meets the baseline for high schema coverage without extra value.

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

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

The description clearly states this is a composite 'should I add this npm package' check that fans out across deps.dev and bundlephobia, listing the exact data sources and fields. This specific verb+resource+scope distinguishes it from all sibling tools, which focus on different entities or research tasks.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and also provides an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This gives clear when-to-use and alternative 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 description adds substantial behavioral detail beyond the annotations: returns passages with character offsets and similarity scores, uses BGE-base-en embeddings + cosine over 500-char overlapping windows, and has a 200K char cap with truncation flagged. These are concrete, non-obvious behaviors that help an agent predict output and 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?

Four sentences, each with a distinct role: core definition, usage guidance, integration with sibling, and technical specifications. No word is wasted, and the most important information is front-loaded. The structure is logical and easy to parse.

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

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

Despite no output schema, the description adequately explains return shape (passages with offsets and similarity scores), the truncation behavior, and integration with a companion tool. It covers the key edge case (character cap) and gives confidence about reversibility and safety through annotations. This is a complete, self-sufficient description.

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 clarifying the 'text' parameter as a fetched record (versus arbitrary text), giving illustrative query examples, and implicitly describing 'limit' via 'top-N passages.' It doesn't just repeat schema; it enriches the meaning of parameters.

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

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

The description uses a specific verb+resource construction: 'Semantic search INSIDE a fetched record.' It clearly distinguishes from sibling tools by emphasizing 'inside a fetched record' and giving concrete examples (SEC 10-K, article). This leaves no ambiguity about what the tool does.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also names a companion tool and explains how they complement: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This provides both inclusion and exclusion context.

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

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

Discloses auth requirement ('Requires a Pipeworx OAuth account'), phone verification and SMS cap, and return value. Annotations (idempotent, readOnly=false) already set safety expectations; description adds operational constraints. 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?

Description is front-loaded with purpose and return value, then covers auth, types, and delivery in a structured way. It is longer than the ideal but every sentence adds necessary detail for a multi-type subscription 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?

Tool is complex (3 params, nested objects) with no output schema; description covers return value, authentication, supported types (partially), and delivery options. The schema fills gaps for remaining types and webhook details, making the description sufficient.

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

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

Schema coverage is 100%, so baseline 3. The description adds value by providing concrete examples for sec_8k (items:['5.02']), polymarket_edge (topic:'fed'), and fred_series (series_id:'UNRATE'), and explaining delivery channel syntax. It omits two types from description but schema covers them.

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 'Create a proactive monitoring subscription to a live-data event stream' and 'Returns the new subscription id', clearly defining the action and output. It distinguishes from sibling tools like list_subscriptions and recent_alerts by focusing on the creation of subscriptions.

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

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

Provides context for when to use: 'proactive monitoring' and mentions pulling alerts via 'recent_alerts or GET registry.pipeworx.io/alerts.json', implying an alternative for one-off retrieval. However, it doesn't explicitly say 'use recent_alerts instead' or exclude cases like one-time data needs.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds meaningful behavioral context: it returns category-bucketed example questions, each with the exact tool and argument shape, drawn from the live catalog. It does not describe any potential limitations or edge cases, but the core behavior is well disclosed.

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; every clause adds value. It front-loads the trigger phrases and then systematically explains what to expect and when to use. It could be broken into shorter sentences for readability, but the structure is logical and 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?

Despite lacking an output schema, the description thoroughly explains the return content (category-bucketed example questions with exact tool + argument shape) and the tool's role in the broader ecosystem (learning meta-tools). It also covers invocation patterns and topic values, making it complete for an agent's needs.

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

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

Schema coverage is 100% and includes a description for 'topic', so baseline is 3. The description adds value by providing concrete examples ('finance', 'pharma', 'betting') and explaining the effect of omitting the parameter (full spread), which clarifies the optionality beyond the schema alone.

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

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

The description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions for what can be asked of Pipeworx. It uses specific verbs ('returns', 'learn') and distinguishes itself from siblings by explicitly positioning it as the 'FIRST' tool to use for onboarding.

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

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

Provides explicit usage 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 call pattern (no arguments vs. passing a topic) and names the meta-tools to learn, giving clear context for when to choose this 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 indicate a write operation (readOnlyHint=false) and idempotence. The description adds vital behavioral context beyond annotations: the row is deactivated, not deleted, preserving historical events via recent_alerts. It also explains ownership enforcement. This provides transparency without contradicting any annotation.

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

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

Two concise sentences deliver the core purpose and key caveats without any fluff. Each sentence earns its place: first states the action, second covers ownership and the soft-delete behavior.

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 one-parameter tool with no output schema, the description covers the operation, a key constraint (ownership), and a behavioral nuance (deactivation not deletion). It doesn't discuss error scenarios or responses, but given the tool's simplicity and the existing annotations, it is sufficiently complete.

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

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

The parameter schema already covers the 'id' parameter thoroughly with a description indicating it's a UUID from subscribe. The description adds limited extra parameter semantics (that the subscription must be owned by the caller) but mostly repeats what the schema conveys. Baseline 3 applies due to high schema coverage.

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

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

The description clearly states the action ('Cancel a subscription by id') and the target resource (subscription). It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by specifying the cancellation operation and the ID-based approach.

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 offers clear context: ownership enforcement implies you use it only for your own subscriptions, and the deactivation note clarifies the non-destructive effect. It doesn't explicitly name alternatives or exclusions, but the intended usage is obvious given the tool name and 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?

Beyond the annotations (readOnly, openWorld, idempotent, not destructive), the description discloses important behavioral nuances: the two-tier routing (structured fast path vs. grounded pipeline), the specific verdict enum values, and the crucial distinction between 'could_not_verify' (failure of the check) and 'unsupported' (no source covers it). It also warns callers not to treat 'could_not_verify' as evidence, which is valuable operational context.

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

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

The description is long but front-loaded with examples and key usage guidance. It contains dense, purpose-driven information such as the pipeline explanation, verdict values, and the 'could_not_verify' caveat. However, the opening list of example phrasings is somewhat redundant and could be trimmed without losing meaning.

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

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

With no output schema, the description fully accounts for the tool's return contract: verdict values, grounded/structured actual value with citation, reasoning, and the verification_error payload in the 'could_not_verify' case. It also states the tool replaces 4–6 sequential calls, covering the operational purpose. The description is complete for an agent to invoke and interpret 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 provides descriptions for both parameters (claim and tolerance_pct) with examples, giving 100% coverage. The description adds extra value by explaining that tolerance_pct overrides the tolerance implied by the claim wording and suggesting 1–2 for hallucination detection. This goes beyond the schema, so it merits above the baseline of 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 opens with concrete natural-language example queries and clearly states the tool does 'natural-language claim verification against authoritative sources.' It explicitly distinguishes between company-financial claims (SEC EDGAR + XBRL fast path) and any other factual claim, and declares its output as a verdict with citations. This is a specific verb+resource that separates it from the sibling research and comparison 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 says 'Use whenever the agent needs to check whether something a user said is factually correct,' which is explicit usage guidance. It also notes that 'could_not_verify' means the check did not happen and should not be treated as evidence. However, it does not name specific alternative tools for cases like comparing entities or deep research, so the guidance is clear but not the strongest possible.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the exact output structure ({ title, implied_probability, url }), the meaning of implied_probability (main/YES outcome or top outcome for multi-outcome markets), and the 'Keyless' auth requirement. This adds substantial behavioral context beyond the structured fields.

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

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

Three sentences: the first gives the primary action and output, the second provides usage guidance, and the third clarifies probability semantics. Every sentence contributes value with no redundancy or padding.

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

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

Despite no output schema, the description fully specifies the return format and field semantics. It includes usage context, authentication ('Keyless'), and probability interpretation. This is complete for a simple top-5 fetch tool, especially with strong annotations covering safety.

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 'query' and 'venue' described. The description only echoes these parameters without adding new semantics (e.g., format, examples, or edge cases). Therefore, the baseline of 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 starts with 'Single-venue drill-down: fetch one venue's current top 5 matches for a query', which clearly states the verb (fetch), resource (venue's top 5 matches), and scope (single-venue). It distinguishes from siblings like compare_topic by emphasizing single-venue 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 explicitly says 'Useful after compare_topic to look closer at one venue', providing a clear when-to-use context and naming an alternative workflow. It doesn't explicitly state when-not-to-use, but the single-venue scope implicitly excludes multi-venue comparisons.

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