Ip Api

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds the default model (Workers AI Llama-3.3-70b, free) and the BYO key cost implication for probing Anthropic, plus the return structure with per-model score, confidence, signals, and raw_response. This goes beyond annotations but doesn't cover rate limits or error behavior, so a 4 is appropriate.

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 core action, and every sentence provides new information (scope, defaults, cost, return structure, use cases) with no fluff 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?

Despite having no output schema, the description explains the return structure (per-model object plus combined view) and covers defaults, authentication key, and use cases. With 4 total parameters and 1 required, this is a complete description for 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%, so the baseline is 3. The description adds value by explaining the default model and the relationship between _apiKey and the 'anthropic' model option, which is not fully captured in the schema. It also states the response shape, further helping the agent understand outputs.

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

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

The description clearly states the tool probes one or more LLMs about a business/brand/product/topic and scores visibility on a 0-100 scale, which is a specific verb and resource. It also lists use cases, but it does not explicitly differentiate from sibling tools like scan_competitor_ai_presence, so it doesn't fully earn a 5.

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 it is useful for AI-marketing audits, pre-launch brand checks, and competitive monitoring, which gives clear usage context. However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context: it routes to many tools, fills arguments, and returns stable pipeworx:// citation URIs. It doesn't mention latency, ambiguity handling, or rate limits, but this is acceptable given the 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 long (~200 words) but front-loaded with the key guidance "PREFER OVER WEB SEARCH" and packed with useful examples and alternative tool pointers. Some redundancy exists (e.g., repeating 'START HERE' and mentioning 'free account'), but it remains well-structured for a complex route-all question 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?

For a simple query tool with one required parameter and no output schema, the description is extremely complete. It covers the full scope of data domains, gives trigger phrases, examples, alternative tools, and describes the return format (structured answers with citations). There is no obvious missing context 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?

Schema description coverage is 100%, with the only required parameter 'question' fully documented and its aliases (query, q, prompt, text, input) explicitly listed. The description adds no extra parameter-level meaning beyond usage examples, 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 it routes questions to 5,334 tools across 1,393 sources and returns structured answers with citations, which is a specific verb+resource. It also explicitly distinguishes from siblings by naming ask_pipeworx_grounded and deep_research, and positions itself as the default entry point.

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: listing trigger phrases ("what is", "look up", "find") and example questions. It also gives clear alternatives: use ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part queries, plus a note for breaking news.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond these by disclosing that candidate routing improvements may be enabled live, the current state (no candidate active), and that it is a fully functional router, not a fallback. This experimental behavior is not evident from annotations alone.

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

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

The description is concise and front-loaded with the core identity ('Beta version of ask_pipeworx'). Each of the four sentences adds relevant information: identical scope, current test status, usage guidance, and operational assurance. Slightly verbose on experimental details but every sentence earns its place.

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

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

The description adequately covers the tool's complexity: universal router, identical to stable version, beta test state, and usage conditions. It mentions 'same response shape' which addresses return value expectations. No output schema is present, but this disclosure suffices. It does not provide examples or edge-case cautions, but for a router tool this is reasonably 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% with aliases for 'question' clearly documented. The description states 'same arguments' as ask_pipeworx, which adds no new semantic value beyond what the schema already provides. 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 explicitly states this is a beta version of ask_pipeworx, an identical universal router with the same 5,334 tools, arguments, and response shape. It clearly distinguishes itself from the stable sibling by emphasizing the experimental edge and current state.

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 it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that results are compared against the stable router, implying when to prefer this over the stable version. However, it does not mention the grounded variant or when not to use it.

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

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

Beyond the provided annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses extra cost ('one extra LLM call'), explicit refusal behavior with specific reason codes, and the return shape including evidence. It adds substantial behavioral 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 information-dense and front-loaded with the core purpose, but it is somewhat long for a tool description. Most details (return shape, refusal reasons, cost tradeoff) are valuable; still, a tighter rewrite could improve scannability.

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

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

With no output schema, the description fully compensates by explicitly detailing both success and refusal return shapes, listing refusal reasons, and explaining the cost/usage tradeoff. This is complete for a complex grounded-question tool with rich annotations and sibling alternatives.

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

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

The input schema has 100% description coverage, with all six parameters documented as aliases for the same natural-language 'question' field. The description does not add parameter-specific syntax beyond what the schema already states, 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?

The description clearly identifies this as a grounded, hallucination-resistant answer mode for high-stakes reads, distinguishing it from ask_pipeworx by emphasizing extraction strictly from tool results with evidence. The verb and resource are specific, and the 'Same routing as ask_pipeworx' contrast makes the purpose unambiguous.

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

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

Explicitly states when to use it ('whenever an answer will be quoted, cited, or acted on... must not invent facts') and when to prefer the cheaper alternative ('prefer ask_pipeworx for casual lookups'). It also names the sibling alternative, meeting the highest standard for usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds extensive behavioral details: parallel fan-out, resolver contract with confidence scores, parent_event extraction, blocking statuses for low-confidence/closed markets, news fallback behavior, and resolution-rule risk with quantified impacts (e.g., flat-50¢ void settlements). No contradiction with annotations.

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

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

The description is long but well-structured with uppercase labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loaded purpose. Every sentence carries useful information, but the length is substantial, with many fan-out examples and detailed edge cases. It earns its place, though a bit more conciseness could push it to 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?

This is a complex tool with 3 parameters and no output schema, so the description carries the full burden. It documents response shapes (result.market, result.analysis, result.evidence), the resolver contract, parent_event extractor, news fallback fields, safety short-circuits, closed-market handling, and resolution-rule risk with specific thresholds and mechanics. This is more than enough for an agent to 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?

Schema description coverage is 100%, so baseline is 3. The description provides examples for the 'market' parameter (slug, URL, question text) which mirrors the schema. It does not add new meaning for 'depth' or 'include_raw' beyond what the schema already states. The fan-out examples give context but not parameter-specific semantic enrichment.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from sibling tools by focusing on single-bet research with data fan-out, and explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z').

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

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

The description gives explicit when-to-use guidance ('Use for...'), but does not mention when-not-to-use or name alternatives such as polymarket_arbitrage or polymarket_edges. It provides clear context and examples, but lacks explicit exclusions or sibling comparisons, so it falls short of a 5.

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

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

Beyond the read-only/idempotent annotations, the description discloses data sources (SEC EDGAR/XBRL for company, FAERS for drug), off-calendar fiscal year handling, and result sorting by primary metric. It also mentions the output includes paired data and citation URIs.

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 front-loaded with purpose and usage guidance. The trigger phrase list is useful for an AI agent, and each sentence contributes meaningful information without 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?

With no output schema, the description explains return format ('paired data + citation URIs'), sorting behavior, and per-type data sources. It provides comprehensive context for both company and drug comparison cases.

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

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

Schema covers parameter basics, but the description adds that 'type' determines which data source is queried and that 'values' are processed in a parallel comparison. This enriches the schema's baseline, though schema coverage is already 100%.

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

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

The description explicitly states it performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with specific trigger phrases. It distinguishes itself from single-pack lookups and sibling tools by noting it replaces 8–15 sequential lookups.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Also gives concrete examples of queries that should trigger this tool, making it clear when to use it.

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

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

The description adds significant behavioral context beyond annotations: auth/paywall requirements, structured-source grounding, parallel tool routing, a findings packet with citations and gaps[], gap-recovery and contradictions[] for deeper depths, semantic excerpting, and latency expectations. The open-world annotation is not contradicted because the tool does access live external structured data even though it is not open-web search.

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 each sentence serves a purpose: auth, positioning, mechanics, output format, and timing. It is front-loaded with the critical account gate and uses clear examples, but could be more scannable with section breaks. Slight verbosity keeps it from a 5.

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

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

With no output schema, the description fully explains return structure (findings packet, citations, gaps, contradictions, hop fields), depth-dependent behavior, and expected latency. It also covers edge cases (lack of data, current-news topics) and account constraints, making it complete for an agent to decide and invoke correctly.

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

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

The schema already covers both parameters with full descriptions, so baseline is 3. The description adds meaning by elaborating depth semantics ('standard' re-angles unanswered gaps, 'thorough' chases leads), giving example question types, and clarifying that questions can be broad/multi-part. This exceeds baseline but does not fully redefine schema content.

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

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

The description states the tool performs grounded multi-source research over Pipeworx's 1393 structured data sources in one call, decomposing questions into facets and routing them in parallel across 5,334 tools. It explicitly contrasts with open-web search and distinguishes from the sibling ask_pipeworx, making its purpose and scope 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?

Explicit guidance is provided: best for broad/multi-part questions over structured data; use ask_pipeworx for single lookups, breaking news, or colloquial current-news topics. It also notes the sign-in requirement and suggests ask_pipeworx for users not signed in. These when/when-not instructions directly address 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 declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral context: it returns top-N results with full schemas and curated examples, and results are directly callable without a second lookup. This goes beyond the annotations without conflicting with 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 efficiently structured: purpose first, then usage context, then return format. The domain list is long but directly informs the agent of the tool's scope. Every sentence earns its place without 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 tool with no output schema and a relatively simple input interface, the description covers when to use it, what it does, what it returns, and how results are formatted. It is self-sufficient for an agent to decide whether and how to invoke it.

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, including detailed aliases for 'query'. The description adds only that the query is a 'natural language description' and lists example queries, which is helpful but not substantial beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task' and enumerates a broad list of supported domains. It distinguishes itself from sibling tools by positioning itself as a meta-tool for discovery, not a specific domain tool.

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

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

Explicitly directs the agent when to use it: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' This provides unambiguous guidance relative to directly calling specific sibling 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 annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses detailed behavior: it fans out across multiple data sources, returns specific fields (CIK, filings, fundamentals, patents, news, LEI), handles a patents API sunset with soft-fail, and falls back from GDELT to GNews. No contradiction with annotations.

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

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

The description is long but every sentence provides essential detail for a multi-source aggregation tool. It front-loads with user-phrase examples, then systematically explains inputs, outputs, and constraints. Could be tightened, but the density is justified by complexity.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly covers return structure (CIK, filings with URIs, fundamentals fields, patents, news, LEI), input limitations (ticker/CIK only), and failure modes (PatentsView soft-fail). It is fully adequate for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the 'value' parameter with examples ('AAPL', '0000320193'), clarifying zero-padding, and emphasizing that names are not supported. This enriches the schema definitions.

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 in ONE parallel call,' with a specific verb ('profile') and resource (US public company). It distinguishes itself from sibling tools by contrasting with 'chaining single-pack SEC/XBRL/news lookups' and referencing 'holistic view'.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also provides a direct alternative: 'use resolve_entity first if you only have a name.' 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?

The description states the destructive nature ('Delete') and aligns with annotations (destructiveHint=true, readOnlyHint=false). However, it adds little beyond the annotations—no mention of irreversibility, key-not-found behavior, or permission requirements. With annotations already covering the safety profile, the description provides minimal extra 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 two sentences, front-loaded with the core action, and each sentence earns its place. It includes the action, use cases, and a pairing note without any fluff 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?

For a simple one-parameter tool with comprehensive annotations and full schema coverage, the description is complete. It explains the purpose, when to use it, and how it relates to sibling tools. No output schema or additional complexity requires further explanation.

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

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

The schema covers 100% of the parameters with a clear description ('Memory key to delete'). The tool description does not add any additional semantic detail about the key format, uniqueness, or behavior when the key doesn't exist. Schema coverage is high, so a 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 action: 'Delete a previously stored memory by key.' This is a specific verb-plus-resource definition that distinguishes it from sibling tools like recall (retrieve) and remember (store). The intent 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?

The description provides explicit usage conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names complementary tools: 'Pair with remember and recall,' offering clear guidance on when to use this tool versus 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 cover safety (readOnly, non-destructive). The description adds behavioral detail about fetching the page, extracting key content, and emitting standard markdown, plus the output format (a text blob ready for site-root). This goes beyond annotations without contradicting them.

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

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

The description is compact and front-loaded with the core purpose. The 'Useful for' section adds practical value without fluff. Every sentence serves a purpose.

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

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

Given the tool's simplicity, the description covers purpose, process, output, and usage scenarios. There is no output schema, but the description explains the return value. Minor gaps (error handling, invalid URLs) are not critical for this straightforward tool.

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

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

Schema description coverage is 100%, and both parameters ('url' and 'max_links') are already well-described in the schema. The description doesn't add extra parameter-specific guidance, so 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 states a specific verb ('generate'), a specific resource ('llms.txt file'), and explains the process (fetch/extract/emit). It clearly distinguishes from sibling tools like scan_competitor_ai_presence which focus on auditing rather than generating.

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

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

The 'Useful for' section provides concrete scenarios (client indexing, own project, auditing competitor), giving clear context on when to use. It does not explicitly list when not to use or alternative tools, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds the scope 'caller's active subscriptions' and lists the returned fields (id, type, params, created_at, last_fired_at, fire_count), giving the agent concrete expectations. It does not contradict annotations.

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

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

Two sentences, front-loaded with the main action, followed by essential output details and a usage note. No unnecessary words.

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

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

For a simple read-only list tool with one optional parameter, the description provides purpose, usage, return fields, and scope. With good annotation coverage and schema, this is 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 covers 100% of the single parameter (include_inactive) with a clear description and default value. The description does not add additional detail about parameter semantics, so 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 clearly states 'List the caller's active subscriptions' with a specific verb and resource, and includes the returned fields. It distinguishes from sibling subscribe/unsubscribe tools by indicating this is for reading current 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?

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel,' which tells the agent when to invoke it (before subscribing) and that it serves the cancellation flow. This provides clear contextual guidance versus 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?

With all annotations set to false, the description carries the full burden of behavioral disclosure. It discloses rate limiting (5 per identifier per day), cost (free, doesn't count against tool-call quota), and outcome (team reads daily, affects roadmap). It also warns against including end-user prompts, which is a meaningful behavioral boundary.

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 adding distinct value: purpose, use cases, content guidance, and operational constraints. No filler or repetition of schema content.

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

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

For a feedback submission tool with optional structured context, the description addresses when, what, and how to provide feedback, plus rate limits and cost. The lack of an output schema is acceptable since the tool's outcome (submission) is obvious. The description is sufficient 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 schema already covers all three parameters with descriptions and enum meanings (100% coverage), so baseline is 3. The description adds nuance on message content ('describe in terms of Pipeworx tools/packs') and the significance of type choices, which lifts it to 4.

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

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

The description opens with a clear action ('Tell the Pipeworx team') and a specific resource ('something is broken, missing, or needs to exist'). It enumerates concrete use cases (bug, feature/data_gap, praise) that map directly to the type enum, and it is easily distinguishable from sibling research/memory/subscription tools, which are information retrieval or preference management operations.

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: for wrong/stale data, missing tools or data, or praise. It also provides content guidance (describe in terms of tools/packs, don't paste the end-user's prompt). While it doesn't name alternatives, the tool's unique function makes exclusions unnecessary.

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 (readOnlyHint, idempotentHint), the description adds valuable behavioral context: it mentions the data source ('derived from CF analytics-engine'), privacy ('no PII'), output shape ('just (pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). This substantially enriches the agent's understanding without contradicting the annotations.

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

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

The description is well-structured and efficient: a one-sentence summary, a compact output list, and a bulleted list of use cases. Every sentence adds distinct value—purpose, output, usage scenarios, and behavioral traits—with no redundancy. It is appropriately sized for the tool's complexity.

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

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

For a read-only tool with no output schema, the description is remarkably complete. It specifies the return content (top tools, packs, call volume), the aggregation source, caching behavior, and privacy implications. The optional window parameter is fully explained, and the use cases provide the context needed to 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 schema covers the single 'window' parameter with a clear enum and description, including the trade-off between short and long windows. The tool description repeats the window options but does not add meaningful new semantic information beyond what the schema already provides. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description opens with 'What other AI agents are calling on Pipeworx right now,' which is a specific and vivid statement of purpose. It goes on to list exact outputs (top tools, top packs, total call volume) and window options, making it unmistakable what the tool does and how it differs from siblings like ask_pipeworx or discover_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 'Useful for' section provides three concrete scenarios (discovering hot data sources, confirming canonical tools, checking alignment with agent needs), giving clear context for when to use the tool. It does not explicitly name alternatives or state when not to use it, but the scenarios are specific enough to guide appropriate selection.

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

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

Despite annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already covering safety, the description adds substantial behavioral context: the fill check logic (realizable_edge_pp ≤ 0 means do not trade), the semantic anchor Jaccard threshold (0.30), the partition filter rules (placeholder slugs, >20% fraction returns null), and the response structure. It clearly explains what happens in various scenarios, going 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 and dense, but the complexity of the tool justifies much of the detail. It is front-loaded with the purpose sentence, but the structure is a single paragraph that could be improved with headers or bullet points. Some redundancy exists (e.g., partition check explained in both event and topic sections), leading to a minor deduction.

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, filters, fill check, response structure) and no output schema, the description thoroughly covers all necessary aspects. It explains default behavior, mode-specific behavior, response fields, the fill check interaction, and cross-event pitfalls. The pointer to polymarket_fill_risk completes the context for follow-up actions.

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 describes both parameters (event and topic) with 100% coverage, but the description adds concrete examples (e.g., 'fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal') and clarifies that full Polymarket URLs are accepted for event. This helps the agent construct valid inputs more accurately than 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 what the tool does: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It further distinguishes the three invocation modes (trending scan, event, topic) and mentions the sibling tool polymarket_fill_risk for custom sizing, making the tool's purpose and scope unmistakable.

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

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

Explicit guidance is provided for each mode: call with no args for a trending scan, pass 'event' for a specific market, pass 'topic' for cross-event scanning. It also recommends event mode for specific markets and directs users to polymarket_fill_risk for custom sizing, clearly indicating alternatives and appropriate contexts.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by detailing output segments, edge calculation specifics (e.g., net of slippage, Kelly caps at 0.25), the 24h-move warning, Fed candidates exclusion rationale, and KV-level caching keyed on knobs. No contradiction with annotations exists; the read-only and idempotent nature is consistent with the described scanning behavior. This rich disclosure earns a top 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 long and dense, but well-organized into clear thematic sections (segments, knobs, response top-level, caching). Every sentence provides useful detail, though some technical specifics (e.g., 'lognormal barrier from 90d FRED log-returns') could be seen as over-specification for an agent deciding whether to call the tool. It is appropriately front-loaded with purpose and use case, but overall it is slightly 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?

With no output schema, the description has the full burden of explaining return values, and it does so thoroughly: it describes the top-level structure (by_segment, fed_candidates, _diagnostics) and the fields within each opportunity (edge_pp_net, kelly_fraction, market.liquidity, etc.). It also covers all 9 parameters and caching behavior. The description is essentially complete for a read-only discovery tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining how knobs interact, such as min_partition_leg_kelly applying to per-leg Kelly rather than parent level, and min_kelly not filtering partition arbs by design. It also explains slippage_pp in the context of Polymarket fees and thin books, enriching the schema descriptions. This goes well beyond the baseline.

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

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

The description opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also frames the intended use case ('what should I bet on today'), distinguishing it from general market data tools. It clearly differentiates from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on opportunity discovery rather than pure arbitrage or historical edge tracking.

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

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

The description provides clear context: it is for discovering betting opportunities without paging hundreds of markets, and it explains knobs for filtering (tradeable-edge, partition leg Kelly). However, it does not explicitly state when NOT to use this tool or mention alternatives like polymarket_arbitrage or polymarket_fill_risk. Since it lacks exclusions or direct alternative comparisons, it earns a 4 rather than a 5.

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

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

Annotations already declare read-only, idempotent, open-world hints. Description adds essential constraints: 60-day snapshot TTL limits history, decay is computed from daily closes (not intraday), snapshot gaps occur on cache-miss. This goes well beyond annotation information and fully discloses data source limitations.

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 long but logically structured into RESPONSE and LIMITS sections, front-loading the purpose. While it restates some parameter defaults also present in schema, each sentence earns its place given the lack of an output schema and the tool's complexity.

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

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

Given no output schema, the description fully specifies the response shape: tracked[] fields, expired[] with lifespan_days, and snapshot_dates[]. It also covers behavioral limits and data provenance, making the tool safe and operable without additional lookups.

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

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

Schema description coverage is 100% and already explains both parameters clearly. Description repeats defaults ('days (lookback, default 14, max 30)') and adds 'snapshot family' terminology, but this adds no new meaning beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states it provides 'Edge persistence and decay telemetry' and frames the exact question: 'how long has this edge existed and is it shrinking?'. This distinguishes it from the sibling polymarket_edges tool by focusing on historical tracking vs. 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?

Usage context is implied via the core question and the emphasis on edge age ('a fresh wide edge and a 3-week-old wide edge are different trades'). It explains the tool's niche relative to polymarket_edges, but does not explicitly name alternatives or state when not to use it.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive, so no contradiction. The description adds rich behavioral context beyond that: it walks the order book ladder, returns a verdict (clean|degraded|cannot_fill), defines the clamping of size_usd, and discloses that partial basket fills convert an arb into directional risk. This is exactly the kind of context that helps the agent trust the tool's 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 tightly structured: purpose first, then mode-specific instructions, then return values, then a direct usage directive. Every sentence carries operational value—mode requirements, field lists, defaults, risk warnings. It is front-loaded with the most important info and avoids filler or repetition.

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

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

With no output schema, the description compensates by enumerating the return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, and basket-mode details like capture_ratio and thin_legs). It also explains the risk context and preconditions. For a tool with two modes and 4 parameters, this is a complete and self-contained specification.

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 substantially enhances parameter meaning. It explains that market and event are mutually exclusive modes, details the side options for each mode (e.g., 'sell_yes = capture overround'), clarifies size_usd interpretation differently for buys vs sells and for basket notional, and mentions the default and clamp. This goes well beyond the schema descriptions.

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

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

The description opens with a precise definition: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' This clearly identifies the tool's function and distinguishes it from siblings like polymarket_arbitrage and polymarket_edges by framing it as a pre-trade risk check. It also names the two modes (single-market and basket), leaving no ambiguity about what it 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?

Explicit usage guidance is given: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when each mode applies and the failure mode (partial fills, unhedged directional risk), which tells the agent not just when but why to use it over 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?

The description goes far beyond the annotations, disclosing the auto-fetch behavior, the compatibility_warning logic, the temporal_alignment field, and the skipped_cross_type/subtype counters. It also warns that most pre-mapped topics return warnings today, setting realistic expectations about output quality.

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 well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS), and every sentence adds substantive information. However, it is quite long with many run-on sentences, making it somewhat less scannable than ideal, so it loses one point.

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, no output schema, and minimal annotation detail, the description is exceptionally complete. It names the response fields (leg-by-leg prices, spread[], compatibility_warning with its two cases, temporal_alignment, and skip counters), covering both functional and edge-case behavior comprehensively.

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 description elaborates on all three parameters beyond the schema by explaining the two modes, how explicit ticker/slug override the topic-mapped side, and providing concrete examples of the topic shortcuts. It clarifies that parameters are optional and how they interact with each other.

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 cross-venue spread calculator between Kalshi and Polymarket for the same resolving question. It differentiates from siblings by focusing on the two-venue comparison and explicitly describes two operation modes (topic shortcuts vs explicit ticker/slug 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 and its limitations, such as warning that incompatible bet shapes mean no arb exists and that aligned:false makes spreads meaningless. It does not explicitly name alternative tools for exclusion, but the dual-mode explanation and caution that 'pre-mapped ≠ tradeable' give strong practical 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 declare readOnlyHint=true and destructiveHint=false, so the safe-read nature is covered. The description adds meaningful behavioral context: scoping to anonymous IP/BYO key/account ID, the ability to list all keys by omitting the key argument, and the 'without re-deriving from scratch' efficiency note. It does not mention what happens for missing keys, but overall it adds value beyond annotations.

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

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

The description is three sentences, front-loaded with the main action, and every sentence adds value: main behavior, use case example, scoping, and companion tools. No fluff, no repetition of schema fields.

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 core behavior (retrieve/list), scoping, use case, and relationships to remember/forget. It lacks explicit mention of what happens if the key doesn't exist or what the returned value looks like, but these are minor gaps given the simplicity and the schema's own documentation.

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

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

Schema description coverage is 100%, with the key parameter already documented as 'Memory key to retrieve (omit to list all keys)'. The description adds context about the nature of saved values (e.g., user's target ticker, address) but doesn't significantly expand on semantics not already in the schema. This meets the baseline for good 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?

Description clearly states: 'Retrieve a value previously saved via remember, or list all saved keys.' The verb+resource is specific, and it distinguishes itself from siblings by referencing remember and forget as the save/delete counterparts. It also provides concrete examples of stored context (target ticker, address) that reinforce its purpose.

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

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

The description gives clear when-to-use context: 'Use to look up context the agent stored earlier — without re-deriving it from scratch.' It also scopes usage to the caller's identifier. While it doesn't explicitly state when NOT to use it or name alternative tools for comparison, the pairing with remember/forget implies a workflow. This is strong but not quite exhaustive.

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 explicitly states that setting mark_read:true flags returned events as read, which is a state-changing operation. This directly contradicts the readOnlyHint=true annotation, making the behavioral description misleading. Annotation Contradiction is flagged.

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

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

The description is concise and well-structured, with three dense sentences each adding value: purpose, return payload/filtering, and an alternative access endpoint. It is front-loaded and free of fluff, though slightly dense.

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 covers the return payload, filtering options, and mark_read behavior, which is useful given the lack of an output schema. However, the contradiction with readOnlyHint creates a significant reliability gap, and no error or pagination details are provided.

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 the parameters, and the description adds meaningful semantics beyond the schema, such as explaining citation_uri (pipeworx://) and how mark_read affects subsequent calls. This enriches understanding of the parameters.

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

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

The description clearly identifies the tool as pulling fired events from a subscription feed and specifies what each event carries. It is specific with verb and resource, though it does not explicitly differentiate from sibling tools like recent_changes.

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

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

The description provides clear usage context: polling works fine, and it mentions an alternative access method via a public URL. It does not explicitly state when to prefer this tool over sibling tools or provide exclusion criteria, but it gives enough context for common use cases.

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

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

The description adds substantial behavior beyond the readOnly/idempotent annotations: it discloses the fan-out architecture, fallback precedence, rate-limit handling, API sunset impact, and the structured response shape. It also documents accepted `since` formats. No contradictions with annotations.

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

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

The description is a dense paragraph but front-loaded with the most recognizable query phrases and quickly moves to concrete details. It is longer than average, but every sentence contributes meaningful information about sources, parameters, fallback behavior, or alternatives. Not a 5 because it could be broken up for readability, but it is efficient.

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

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

With no output schema, the description carries full responsibility for explaining the return value, and it does: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs.' It also covers all parameter semantics, error-prone conditions (rate limits, API sunset), and alternative tool selection. This is complete for a tool of this complexity.

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

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

The input schema already covers all three parameters at 100% coverage, so the baseline is 3. The description adds extra value by providing concrete examples for `since` ('7d', '30d', '3m', '1y'), recommending '30d' or '1m' for typical monitoring, and clarifying that `value` accepts either a ticker or a zero-padded CIK—improving on schema descriptions.

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

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

The description opens with concrete query patterns ('What's new with X', 'latest on Y') and clearly states it is a change feed for a company over a window. It names three specific data sources (SEC EDGAR, GDELT/GNews, USPTO) and contrasts with the sibling entity_profile, making its purpose unmistakable.

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

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

It explicitly states when to use this tool (for recent changes) and when to use an alternative: 'Use entity_profile instead when you want the static profile...' It also explains the fallback behavior between GDELT and GNews, and the USPTO soft-fail, giving clear operational context.

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

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

Annotations already indicate this is a write operation (readOnlyHint=false), so the description doesn't need to repeat that. It adds valuable behavioral context: memory is scoped by the agent's identifier, persistence varies by auth status (authenticated vs. 24-hour retention for anonymous), and it's designed as a key-value store. This goes beyond the annotations without contradicting them.

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

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

The description is four sentences, front-loaded with the core purpose. Each sentence adds necessary context: what to save, when to use it, how storage works, and related tools. There is no redundant phrasing or filler, making it appropriately concise for the tool's simplicity.

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 no output schema, the description is highly complete. It covers purpose, usage examples, persistence semantics, and interaction with sibling tools (recall, forget), leaving minimal ambiguity. The idempotentHint annotation also reassures about repeated writes, and the description aligns with that.

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 both parameters with descriptions for 'key' and 'value' at 100% coverage, so the baseline is 3. The description reinforces the key-value nature and gives examples of keys ('resolved ticker, target address') and values ('findings, addresses, preferences, notes'), but it doesn't add significant new 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's function with a specific verb and resource: 'Save data the agent will need to reuse later.' It also distinguishes this tool from siblings by explicitly pairing it with 'recall to retrieve later, forget to delete,' making its role in the memory workflow unambiguous.

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

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

The description provides explicit guidance on when to use the tool ('Use when you discover something worth carrying forward') with concrete examples like 'a resolved ticker, a target address, a user preference.' It also names alternatives (recall, forget) and explains persistence differences between authenticated and anonymous sessions, giving clear context for appropriate use.

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

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

The description adds rich behavioral context beyond the annotations: it reveals internal cascading lookups ('Each call cascades through several lookup endpoints internally'), describes output details (ticker, CIK, RxCUI, citation URIs), and notes auto-disambiguation. This goes well beyond the readOnly/idempotent annotations.

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

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

The description is front-loaded with examples and a clear purpose, then structured into SUPPORTED TYPES with nested details. Every sentence adds value, and the formatting with quotes and capitalization aids readability. It is concise for the amount of critical information it carries.

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

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

Given no output schema, the description thoroughly explains what the tool returns for both supported types, including citation URIs. It also covers usage guidance and parameter acceptance. The description is fully self-sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances parameter semantics with examples and notes that the 'value' parameter accepts multiple formats (ticker, CIK, name) and mentions auto-disambiguation. However, it repeats some schema information, so it doesn't earn a 5.

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

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

The description states the tool's exact function: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It provides concrete examples and lists supported entity types, distinguishing it clearly from sibling tools that handle other aspects of entity relationships.

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID' and gives example user queries like 'What's the ticker for…' This clearly indicates the primary use case and positions it as the go-to tool for name-to-ID resolution, even if it doesn't name an alternative.

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

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

The description discloses that the tool probes each entity via ai_visibility_check, which is a key behavioral trait (orchestration/sub-call). It also mentions the output structure (ranked list with score, confidence, signal density). Annotations already provide readOnly, openWorld, idempotent, and non-destructive hints, and the description's additional context complements these without contradiction.

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

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

The description is three sentences, front-loaded with the core function, and every sentence adds information (function, mechanism, use case, output). No filler or repetition.

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

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

Given there is no output schema, the description appropriately details the return value (ranked list with score, confidence, signal density). It also explains the entity ordering semantics and the underlying probe. It could mention potential errors or rate limits, but for a read-only orchestration tool with annotations, it covers the essential context.

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

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

Schema coverage is 100%, and the description adds valuable semantics beyond the schema: the first entity is the 'subject' for narrative, rest are competitors; it also explains how the models parameter behaves ('Omit for just workers-ai') and that context disambiguates common names. This goes beyond the structured field descriptions.

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

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

The description clearly states the tool's purpose: comparing AI visibility across multiple entities side-by-side, probing each with ai_visibility_check, ranking by score, and surfacing most/least recognized. It distinguishes itself from sibling tools by explicitly focusing on competitive comparison, and even references the underlying single-entity probe (ai_visibility_check).

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

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

The description provides a clear use case ('competitive AI-marketing audits') with a concrete example. It does not explicitly state when not to use it or name alternative tools, but the comparison-oriented context makes its intended usage evident.

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

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

The description discloses important behavioral traits beyond the annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. This adds valuable context about latency and error handling that annotations alone do not provide.

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

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

The description is a dense paragraph but every sentence earns its place: it states the core purpose, gives usage triggers, lists output fields, notes ecosystem scope, and explains failure behavior. It is front-loaded with the main purpose and not padded, despite its length.

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

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

With no output schema, the description fully compensates by listing the summary block fields, per-advisory details, links, and alternative versions. It also covers edge cases like bundlephobia timeouts and non-npm ecosystems, making the tool's behavior and results predictable 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 description coverage is 100%, so the schema already documents both parameters. The description mentions 'Defaults to the latest published version when omitted', which is already in the schema, and adds no extra semantic meaning about parameter constraints or usage. 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 defines the tool as a composite 'should I add this npm package' check that fans out across deps.dev and bundlephobia. It enumerates the specific data sources and output components, distinguishing it from sibling tools by its single-call aggregation and ecosystem 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 states when to use it: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion by noting 'NPM ecosystem only in v1' and directs other ecosystems to deps.dev:version directly, offering clear when-not 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 discloses concrete behavioral details beyond the annotations: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' It also states return format ('top-N passages with character offsets and similarity scores'). These enrich the annotation hints (readOnly, idempotent) without contradiction.

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

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

The description is dense but every sentence earns its place: it covers purpose, usage, pairing, technical mechanics, and constraints in a front-loaded, well-organized manner. There is no redundant or filler language.

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 and lack of an output schema, the description provides a complete picture: inputs, outputs (top-N passages with offsets and scores), technical approach, limits/truncation, and a paired alternative. Nothing essential is missing for an agent to decide 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?

Schema coverage is 100% with each parameter already described, but the description adds genuine semantic meaning: it clarifies 'text' is a previously fetched record, gives example queries ('supply-chain risk', 'fiscal year 2024 revenue') for the query param, and specifies limit's role as 'Max passages to return.' This goes beyond simple schema descriptions.

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

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

The description clearly states a specific verb and resource: 'Semantic search INSIDE a fetched record.' It immediately distinguishes itself from sibling tools by emphasizing that the text is already pulled by the agent, not fetched externally. The examples (SEC 10-K, article) solidify the purpose.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt' and 'search_within saves context, returns only the passages that matter.' It also names a complementary pair: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This provides clear when-to-use and alternative context.

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

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

Annotations already indicate a write operation (readOnlyHint false) and idempotency. The description adds substantial behavioral specifics: OAuth requirement, phone verification for SMS, 10/day SMS cap, always-on feed with retrieval methods, and webhook signing/disabling details in the schema. These go 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?

A single paragraph, front-loaded with the primary action, and every sentence carries useful information. Examples are compact and illustrative without being 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?

Covers purpose, prerequisites, supported types, delivery channels, and return value. Omits explicit mention of webhook in the main description (though schema covers it in detail) and does not address error cases. Given the schema's richness and sibling tools filling gaps, this 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?

Schema has 100% coverage, providing a baseline of 3. The description adds concrete examples (items:['5.02'] meaning officer change, topic:'fed', series_id:'UNRATE') that enrich understanding of how to construct params. It does not cover all parameter nuances, but the schema does; the examples add 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 opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It distinguishes from sibling tools like list_subscriptions and unsubscribe by clearly indicating creation. The supported types are enumerated, further clarifying the 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?

Gives contextual guidance: requires OAuth, mentions anonymous/BYO incompatibility, and describes delivery channels. It mentions how to pull the feed via recent_alerts, but does not explicitly state when to use this tool versus alternatives like recent_alerts or list_subscriptions. No exclusions are given, but the prerequisites and channel options provide clear context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it returns category-bucketed example questions with exact tool+argument shapes from a live catalog. This goes beyond the safety profile to explain the output structure and the effect of passing a topic.

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 adds value: it lists example questions, defines the return structure, explains parameters, and gives usage guidance. It is well-organized, front-loading the purpose and immediately distinguishing it from siblings.

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, the description fully covers what the agent needs: it lists return categories, explains the argument shape included with each question, and describes the live-catalog source. This is sufficient for correct invocation and expectation-setting.

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

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

Schema coverage is 100% with a description for the topic parameter. The tool description goes further by providing concrete examples ('finance', 'pharma', 'betting') and explaining the behavior when omitted ('Omit for a cross-category spread'). This adds practical semantics beyond the schema.

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

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

The description clearly states the tool's role as an onboarding entry point: 'the onboarding entry point for an agent that just connected and wants to know what is worth asking.' It uses a specific verb+resource and distinguishes from siblings by being the FIRST tool to use when unfamiliar with Pipeworx.

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

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

Explicitly provides when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also explains the optional topic parameter and what happens when omitted, giving clear context for choosing this tool over 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 provide safety hints, but the description adds valuable behavioral context: ownership enforcement, deactivation instead of deletion, and historical events remaining available via recent_alerts. This goes well beyond the structured annotations.

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

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

Two concise sentences, front-loaded with the action, and every sentence adds useful information. 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?

For a simple single-parameter cancellation tool with good annotations, the description covers the essential behavioral aspects. It doesn't mention the return value, but that's minor given the simplicity and idempotency hint.

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 explains the id parameter as a subscription uuid from subscribe. The description doesn't add parameter-level detail beyond what the schema provides, so 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 uses a specific verb ('Cancel') and resource ('a subscription by id'), clearly distinguishing from sibling tools like subscribe and list_subscriptions. It also adds the deactivation nuance, which sets it apart from any delete-like sibling.

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

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

The description gives clear context: use this to cancel your own subscription, with ownership enforced and deactivation not deletion. It doesn't explicitly mention alternatives or exclusions, but the context is obvious given sibling tool names.

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 the internal routing logic, the exact verdict categories (confirmed, approximately_correct, refuted, inconclusive, unsupported), the inclusion of verbatim evidence and pipeworx:// citations, and the tolerance default behavior. This provides rich behavioral context that annotations alone do not cover.

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

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

The description is fairly long but well-structured, starting with colloquial trigger phrases, then purpose, routing, output, and efficiency comparison. Each sentence contributes unique information; however, a few phrases could be tightened without losing meaning, making it slightly verbose for a tool description.

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 fully covers the return values (verdict, grounded/structured value, citation, reasoning), the two routing paths, and typical usage scenarios. It also explains the tolerance behavior and the comparison logic, leaving minimal ambiguity for an agent to 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?

Schema coverage is 100% (both parameters described), but the description adds significant value by explaining how tolerance_pct overrides claim-implied tolerance, including the specific use case of 1–2 for hallucination detection. The claim parameter's examples further clarify expected input format, exceeding baseline schema information.

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

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

The description explicitly states the tool's function: natural-language claim verification against authoritative sources, with specific verbs like 'fact check' and 'verify'. It clearly differentiates from siblings by describing the two routing paths (SEC EDGAR + XBRL vs grounded pipeline) and the replacement of 4–6 sequential calls, making its unique role evident.

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 direct usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further distinguishes between company-financial claims (fast path) and any other factual claim (grounded pipeline), and mentions it replaces multi-step processes, implicitly positioning it as the go-to verification tool among siblings.

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