Pkg Go Dev

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable behavioral details: default model is free (Workers AI Llama-3.3-70b), Anthropic requires a BYO key with direct billing, and the return structure includes per-model and combined views. No contradictions.

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

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

The description is two sentences long, with the core purpose front-loaded. Every sentence adds value: main function, default behavior, optional key, and return format. 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?

Despite no output schema, the description clearly specifies the return structure (per-model {score, confidence, signals, raw_response} + combined view). The tool is simple (4 params, 1 required) and the description covers all essential aspects for correct invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning: it explains that omitting models defaults to workers-ai, that _apiKey is only needed for anthropic, and that context disambiguates. This goes beyond the raw 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 uses specific verbs (probe, score) and identifies the resource (LLMs) and output (visibility 0-100). It clearly states the tool's function and distinguishes itself from generic search tools by focusing on AI visibility auditing. Sibling tools like scan_competitor_ai_presence may overlap, but the description carves a niche for brand/product/topic checks.

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

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

The description explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains conditional usage—default model vs. Anthropic with BYO key. While no direct exclusions or alternatives are named, the context is sufficient for an agent to decide when to invoke this tool.

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

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

Annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false) already cover safety and read-only behavior. The description adds valuable behavioral context: routes questions, fills arguments, returns structured answers with stable pipeworx:// URIs, works on every tier, and is one fast call. No contradictions with annotations; slight omission of failure modes or rate limits keeps it from a 5.

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

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

Although the description is long, every sentence earns its place. It opens with the most critical guidance ('PREFER OVER WEB SEARCH'), then details the mechanism, trigger phrases, examples, and alternatives. No fluff or redundancy; the structure is front-loaded and logically organized.

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

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

Given the tool's broad scope and the absence of an output schema, the description is remarkably complete. It explains what the tool returns (structured answer with citation URIs), its coverage areas, time-related works, and how it relates to other tools. It fully prepares an agent to use it correctly in most situations.

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 all parameters (100% coverage) and describes the 'question' property with alias support. The description enhances this by providing multiple concrete question examples ('current US unemployment rate', 'Apple's latest 10-K') and clarifying that natural language is expected, adding meaning beyond the schema.

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

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

The description clearly states the tool's purpose: it answers factual questions by routing them to one of 5,439 tools across 1,412 sources and returns structured answers with citation URIs. It explicitly distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research, naming what each alternative is for.

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 instructions, including 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and 'START HERE for most questions'. It also provides step-up alternatives: use ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions, plus examples.

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, open-world, idempotent annotations, the description discloses experimental behavior, the potential for live candidate improvements, the current equivalence to ask_pipeworx, and the fact that it is a full working router with no fallback. This gives clear expectations about the tool's operational nature.

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 slightly long but front-loaded with the key beta identity and purpose. Each sentence provides context (routing improvements, current state, usage guidance, fallback), and no sentence is wasted.

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 rich annotations and complete schema, the description covers the experimental nature, usage context, comparison process, fallback behavior, and response shape. It provides sufficient context for an agent to use the tool correctly.

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

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

Schema description coverage is 100% with detailed descriptions for all parameters, including aliases. The tool description only says 'same arguments' without adding further meaning, so the schema carries the semantic burden.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router that routes natural language questions to 5,439 tools. It distinguishes itself from the stable ask_pipeworx by its experimental status and candidate routing improvements.

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

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

It explicitly states when to use the tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes the current state (no candidate active) and that results are compared against the stable router. However, it does not explicitly exclude alternative tools like ask_pipeworx_grounded.

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

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

Even with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description adds substantial behavioral detail: exact refusal reasons, verbatim evidence quotes, and the extra LLM call. It does not contradict annotations.

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

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

The description is dense but efficient, with a clear hierarchy: purpose, mechanism, return values, use cases, and tradeoff. Every sentence contributes meaning, and the structured return/refusal lists make it scannable.

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

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

Given no output schema, the description fully explains both success and failure outputs, the routing behavior, and the cost tradeoff. It is sufficient for an agent to decide when to use it and interpret results.

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

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

The schema description coverage is 100% (all parameters are aliases for 'question' with descriptions), so the parameter baseline is 3. The description doesn't add new parameter syntax but contextualizes the question type (high-stakes, quoted/cited), adding minor value.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and explicitly contrasts with ask_pipeworx by adding evidence-based extraction. It identifies a specific verb-like behavior (answers using only tool result content) and distinguishes from siblings.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' Also mentions the additional LLM call cost, making the tradeoff clear.

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

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

The description goes far beyond annotations, detailing internal behavior: market resolution, classification, fan-out to data sources, response structure (market_match_confidence, parent_event extractor, news fields with fallback info), safety checks (low-confidence, closed markets, wide spreads), and resolution-rule risk. Annotations already declare read-only, idempotent, open-world, and non-destructive, and the description adds extensive context 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 lengthy with multiple paragraphs and sections. While well-structured with headers, it could be more concise. The first sentence fronts the purpose, but overall verbosity reduces clarity for quick parsing. A more streamlined version would improve score.

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 (multiple data sources, resolution logic, safety checks) and lack of output schema, the description is highly comprehensive. It covers response shapes, resolver contract, parent events, news fallback, safety mechanisms, and resolution risks, providing all necessary context for correct usage.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema: for 'depth', it explains 'quick = 2-3 evidence sources, thorough = full fan-out. Default thorough.' For 'market', it specifies accepted formats. For 'include_raw', it explains the tradeoff between response size and detail. This enriches parameter understanding.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet) and action (research with data pull). Usage examples like 'Use for "should I bet on X"' further clarify, and the tool is distinct from siblings like polymarket_arbitrage or polymarket_edges, which focus on different aspects.

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

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

The description explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and includes detailed guidance on how the tool resolves and fans out data. It also instructs the agent to inspect confidence before trusting analysis. However, it does not explicitly mention when NOT to use this tool versus alternatives, which would elevate it to 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 declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. Description adds: off-calendar fiscal years handled correctly, results sorted by primary metric, returns paired data with citation URIs per entity. No contradiction.

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

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

Description is concise yet comprehensive. It mixes examples, behavioral notes, and usage guidance in a logical order. Every sentence adds value without redundancy.

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

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

Covers return format (paired data, citation URIs), sorting, data sources, entity types, and edge cases like off-calendar fiscal years. No output schema, but description adequately explains what the tool returns.

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

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

Schema coverage is 100%, but description adds crucial context: for company type, pulls latest 10-K revenue/net income/cash/long-term debt; for drug, pulls FAERS adverse-event counts, FDA approvals, trial counts. Also explains maxItems=5 and minItems=2.

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 explicit examples ('Compare X and Y', 'X vs Y') to define purpose: side-by-side comparison of 2-5 companies or drugs. It specifies data sources per type and distinguishes from sequential lookups by explicitly stating 'ALWAYS PREFER over sequential single-pack 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 clear when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Also explains that for largest/most queries, results are sorted by primary metric, aiding correct invocation.

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 readOnlyHint/idempotentHint/destructiveHint, so description doesn't need to prove safety. Description adds valuable behavior: account requirement, throws gaps[] instead of inventing, returns contradictions[]. It could mention rate limits or whether the tool blocks, but given annotation coverage, this is strong.

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?

Packed with high-value info but a dense wall of sentences without line breaks, mixing account setup, tool comparison, processing details, and examples. Could be restructured with bullets. It is front-loaded with the account warning, which is important, but overall size is excessive for the 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?

Despite no output schema, the description fully covers return format (findings packet with verbatim evidence + confidence + source + fetched_at + citation URI), gaps[] behavior, contradictions[], hop field, latency expectations, and input types. For a 2-param tool with rich annotations, it is effectively 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 already covers both params 100%, so baseline is 3. Description adds nuance: depth:'quick'/'standard'/'thorough' semantics are explained with facet counts and hop behavior, and 'question' guidance says broad/multi-part is fine. The param descriptions already cover most, so a 4 is fair.

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

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

States specific verb+resource: grounded multi-source research across Pipeworx's structured data sources, distinguishes from ask_pipeworx (single lookup) and open-web search. The first sentence makes scope explicit (NOT open-web search) and later gives examples.

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

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

Explicitly says when to use this tool vs alternatives: use ask_pipeworx for single lookups, for breaking/colloquial current news, or when not signed in. Also explains depth tier tradeoffs and second-hop behavior, giving clear guidance on selecting depth.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds that it returns top-N tools with full schemas and curated examples, ready to call directly, without needing a second lookup.

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

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

Description is front-loaded with core purpose and includes a detailed list of domains, which is useful but slightly verbose. Every sentence contributes value.

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

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

Given 6 parameters, no output schema, the description explains the output format (top-N, schemas, examples) and that results are ready to call. Covers all essential aspects for the agent to use the tool effectively.

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

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

Schema coverage is 100%. Description adds meaning beyond schema by explaining that query is natural language, lists aliases, and provides examples of how to phrase the query.

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

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

The description clearly states the tool finds tools by describing data or task, lists supported domains, and distinguishes itself from siblings by recommending to call it first when many tools are available.

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

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

Explicitly says when to use (browse, search, discover) and advises to call this first when you have many tools. Lacks explicit when-not-to-use but provides strong contextual guidance.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses the tool fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), returns specific fields like recent filings and fundamentals, and notes soft-fail behavior for patents and a fallback for news. 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 moderately long but front-loaded with examples and key guidance. Every sentence provides useful information, though a more structured format (e.g., bullet points) could improve readability. Still, it is efficiently packed without redundancy.

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

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

Given no output schema, the description thoroughly explains return values (cik, company name, recent filings with URIs, fundamentals, patents, news, LEI) and behavioral details like soft-fail and fallback. It covers all aspects needed for an agent to understand what the tool provides.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by providing example values (e.g., 'AAPL', '0000320193'), reinforcing that names are not supported, and explaining the `type` enum only supports 'company'. This goes beyond the schema but is not extensive.

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

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

The description clearly states the tool retrieves a full cross-source profile of a US public company in one parallel call, with examples like 'Tell me about X' and explicit preference over chaining single-pack lookups. It distinguishes from sibling tools like `resolve_entity` by noting that names are not supported.

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

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

The description explicitly states when to use this tool ('ALWAYS PREFER over chaining... when the user asks for a holistic view') and when not to use it ('Names not supported - use resolve_entity first if you only have a name'), providing clear alternatives.

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

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

The description adds context beyond annotations, such as the memory being 'previously stored' (implying the key exists) and the use case for clearing sensitive data. Annotations already indicate destructive and idempotent behavior, but the description enriches understanding 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 a single sentence that efficiently conveys the core action, usage guidelines, and complementary tools. No redundant or unnecessary text.

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

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

For a single-parameter tool with no output schema, the description covers all necessary aspects: purpose, usage context, and relationship to siblings. Annotations handle behavioral details, making the definition complete.

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

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

The input schema has 100% coverage with a clear description of the 'key' parameter ('Memory key to delete'). The description adds minimal extra meaning ('by key'), 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 explicitly states the action ('Delete') and the resource ('previously stored memory by key'). It distinguishes itself from sibling tools by mentioning pairing with 'remember' and 'recall', making the purpose clear and differentiated.

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 concrete scenarios for when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also advises pairing with 'remember' and 'recall', offering clear guidance on usage.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds that it fetches the page and extracts title/description/key links, and output is a single text blob. No contradictions. Minor gap: no mention of rate limits or page size constraints.

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

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

Three sentences, each serving a purpose: purpose and audience, process, use cases. Front-loaded with key info. No redundant or unnecessary text.

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

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

Covers main purpose, process, output format, and use cases. Lacks mention of error handling or limitations, but for a simple, safe, read-only tool this is largely sufficient.

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

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

Schema coverage is 100% (url and max_links have descriptions). Description provides general context but does not add parameter-specific meaning beyond what's in 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?

Clearly states the verb (Generate), resource (llms.txt file), and the process (fetches page, extracts elements, outputs markdown). Distinguishes from sibling tools like scan_competitor_ai_presence by focusing specifically on generating the standard llms.txt format.

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 lists three use cases (indexing a client's site, drafting for own project, auditing competitor). Does not provide exclusions or compare to alternatives, but the context is clear and actionable.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, fully covering safety and idempotency. The description adds minimal behavioral context beyond 'raw contents' (implying text output). With annotations present, the bar is lower, but the description does not elaborate on what 'raw' means or any potential variations (e.g., error states).

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

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

The description is a single well-formed sentence that states the core function and a use case. Every part is meaningful and there is no redundancy or waste.

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

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

With rich annotations, a simple schema of two parameters, and an output schema (not shown here), the description is largely complete. It could briefly note that the output is raw text, but the output schema presumably covers that. The description is sufficient for the tool's simplicity.

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%, meaning both parameters ('version' and 'module_path') are described in the schema. The description repeats the idea of 'specific version' but adds no new semantic detail beyond what the schema already provides. Baseline 3 is appropriate given the high coverage.

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

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

The description clearly states the tool provides 'raw go.mod contents for a specific version' and mentions a concrete use case ('dependency analysis'). This verb+resource combination clearly distinguishes it from siblings like get_module_info or list_versions.

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

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

The description gives an implied usage context ('dependency analysis') but does not explicitly state when to use this tool versus alternatives like get_module_info (which returns structured info) or scan_dependency (which analyzes dependencies). No exclusion criteria or specific scenarios are mentioned.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds specifics about the metadata fields returned, complementing annotations without contradiction.

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

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

Single sentence front-loaded with key purpose, no unnecessary words. Efficiently conveys the tool's function.

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 2 well-documented params, comprehensive annotations, and an output schema (not shown but present), the description is largely complete. Could mention handling of invalid versions but openWorldHint implies flexibility.

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. Description does not add meaning beyond the schema's parameter descriptions (e.g., version semver-ish, module path).

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

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

Description clearly states it returns metadata (resolved version, commit time, origin) for a specific version, distinguishing it from sibling tools like list_versions or get_go_mod.

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

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

No guidance on when to use this tool vs alternatives such as list_versions or get_go_mod. The context signals and sibling list indicate related tools but the description offers no comparative usage advice.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds only the 'resolved time' output detail, which is useful but minimal beyond annotations.

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

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

The description is a single efficient sentence with no filler. It front-loads the core purpose ('most recent released version') and adds a key output trait afterward.

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

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

Given the tool's simplicity (one parameter, output schema exists), the description is reasonably complete. It explains the main action and a notable output attribute. The only minor gap is clarifying the resolved time field, but the output schema likely covers 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?

Schema description coverage is 100% with a clear description for module_path. The tool description does not add extra meaning to the parameter, so it meets baseline expectations.

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

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

The description clearly states the tool retrieves the most recent released version of a Go module with a resolved time, using specific verb-resource language. It distinguishes from siblings like list_versions by focusing on a single latest version.

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

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

The description implies usage for getting the latest version but does not explicitly state when to use it over alternatives like list_versions or get_module_info. No exclusions or alternative recommendations are provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by specifying the return fields and the effect of the 'include_inactive' parameter, going beyond the annotations.

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

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

Two sentences with no redundancy. The first sentence immediately states the purpose, and the second provides usage context. Every word 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?

Despite lacking an output schema, the description fully covers the tool's behavior, parameters, and return values. It is self-contained and sufficient for an agent to use correctly.

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

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

Schema coverage is 100% with clear parameter description. The description adds context about the returned fields, which complements the schema and helps the agent understand the tool's output.

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

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

The description clearly defines the tool's action ('List') and resource ('the caller's active subscriptions'). It also enumerates the returned fields, distinguishing it from siblings like 'subscribe' and 'unsubscribe'.

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

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

Provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This indicates when to use the tool, though it does not explicitly state when not to use it.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds that it fetches from proxy.golang.org (external source) and returns sorted semver strings, which are behavioral details beyond annotations.

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

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

Two sentences, first sentence states action and parameter, second sentence states output format. 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?

Given the tool's simplicity and the presence of output schema, the description covers core functionality. Could mention error handling but not essential.

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

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

Schema coverage is 100% for the single parameter, and the description reiterates the parameter's purpose but does not add substantial new meaning beyond the schema examples. 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 it lists all published versions of a Go module by import path from proxy.golang.org, and returns sorted semver strings. This clearly differentiates it from siblings like latest_version and get_module_info.

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?

While not explicitly stating when not to use, it clearly describes the tool's scope. An agent can deduce to use this for all versions, and use latest_version for the latest only.

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 all annotations being false, the description adds critical behavioral context: rate limiting ('5 per identifier per day'), that it does not count against tool-call quota, and that feedback is read daily and affects roadmap. These details go far beyond the annotations and help set agent expectations.

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

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

The description is longer than typical but every sentence earns its place: it covers what, when, when-not, content quality, rate limits, and impact. It is front-loaded with the verb and purpose, then expands into necessary caveats. Slightly dense but not bloated.

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

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

For a feedback tool with no output schema and moderate parameter complexity, the description is complete. It explains the tool's purpose, usage scenarios, exclusions, message content guidelines, rate limits, and even the feedback consumption process. No relevant behavioral or usage aspect is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra semantic guidance beyond the schema, particularly for the message field ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and provides overall context for the type enum.

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 purpose with a specific verb ('Tell the Pipeworx team something is broken, missing, or needs to exist') and clearly distinguishes it from sibling research and utility tools. It enumerates the types of feedback (bug, feature, data_gap, praise) and explicitly scopes it to the Pipeworx connection.

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 for each feedback type, and an explicit when-not-to-use exclusion for tools from other MCP servers. It also offers a fallback heuristic for identifying Pipeworx tools ('Pipeworx tool names are the ones this connection lists').

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 readOnly, idempotent, openWorld, non-destructive. Description adds caching behavior, data source, no PII, output clarity, which exceeds annotation-only knowledge.

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?

Well-organized with bulleted use cases and clear structure, though slightly verbose. All sentences earn their 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?

With one optional param and no output schema, description sufficiently explains expected output (top tools, packs, call volume) and caching, making tool usage clear.

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 fully (100%). Description adds value by explaining effect of window length (hot vs. steady-state), exceeding enum labels.

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

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

The description clearly states the tool returns trending tools, packs, and call volume over windows, and distinguishes from siblings like discover_tools by focusing on what other agents are calling.

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

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

Lists three specific use cases (discovering hot data sources, confirming canonical choice, aligning use case) and explains window trade-offs, but does not explicitly exclude 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 declare readOnlyHint, idempotentHint, and nondestructive behavior, which the description reinforces and extends with detailed algorithmic context (semantic anchor, partition filter, fill check). No contradictions exist.

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

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

The description is detailed and well-structured, but somewhat lengthy (~300 words). Some technical details could be condensed, but overall it remains focused and front-loads key usage modes.

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

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

Despite no output schema, the description fully explains the response structure (opportunities array, partition check fields, fill check details). It covers all necessary context for correct tool invocation given complexity of 2 optional params.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The tool description adds significant value by explaining how each parameter is used (event slug, topic seed question) and providing examples, enhancing understanding beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific purposes, making it easy for an agent to understand what the tool does and when to use each.

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 each mode: no args for trending scan, event for specific market (recommended), topic for cross-event scanning. It also includes fill check instructions and warns against trading when realizable_edge_pp ≤ 0, offering clear usage boundaries.

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=true and destructiveHint=false, and the description adds rich behavioral context: details on model families, caching at 1h KV level keyed on all knobs, diagnostics, and Fed note. 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 long but well-structured with clear sections and front-loaded purpose. Every sentence adds value, though the density may be slightly high for quick scanning.

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

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

Given the complexity (9 optional parameters, no output schema, rich internal logic), the description is remarkably complete. It covers response structure, diagnostics, edge cases (Fed bets), and caching behavior.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining parameter interactions (e.g., min_partition_leg_kelly vs min_kelly), defaults, and rationale for slippage_pp and liquidity filters.

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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It explicitly names three model segments and distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description provides extensive guidance on when to use (what should I bet on today) and how to adjust knobs (min_liquidity, max_spread_pp, etc.). However, it does not explicitly state when not to use or list 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds significant behavioral context beyond annotations: it explains data bounded by 60-day snapshot TTL, snapshots only on cache-miss (gaps mean no scan), decay from daily closes not intraday, and output structure including trend computation. 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 front-loaded with the core purpose, followed by args and response structure, then limitations. It is moderately long but every sentence adds value. Minor redundancy could be trimmed (e.g., 'daily polymarket_edges snapshots' repeated). Overall well-organized for the complexity of the tool.

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

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

Despite having no output schema, the description thoroughly details the response structure: tracked array with full time-series, first_seen, trend, decay_pp_per_day; expired array with lifespan_days; snapshot_dates. It also covers limits (60-day TTL, snapshot start time, intraday vs daily). This provides complete context for agent usage.

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

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

Schema covers both parameters (days, window) with descriptions. The description adds value by specifying default values (14 days, '1wk'), clamping behavior (max 30), and enumerating snapshot families ('24hr', '1wk', '1mo') which are not listed in the schema. This provides concrete options beyond schema documentation.

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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots,' answering 'how long has this edge existed and is it shrinking?' It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series telemetry rather than current edges. The verb and resource are specific and non-tautological.

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 strong usage context by explaining that a fresh wide edge and a 3-week-old wide edge are different trades. It implies when to use this tool (to assess edge persistence) but does not explicitly name alternative tools or state when not to use it. The guidance is clear but could be more definitive with exclusion criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds valuable behavioral context: how it walks the order book, auto-detects side in basket mode, returns verdict, and highlights the dominant loss mode. No contradictions.

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

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

Long but well-structured with clear headings and bullet-like lists. Every sentence adds value, though could be slightly tighter. Front-loads essential warnings and mode distinction.

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

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

No output schema exists, but the description fully enumerates return fields for both modes, explains risk of partial fills, and provides enough context for an agent to use it correctly. Highly complete for a complex two-mode tool.

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

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

Schema coverage is 100% but the description adds meaning: explains default side behavior in basket mode, interprets size_usd differently for buys vs sells and for single vs basket, and clarifies market vs event exclusivity.

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?

Describes two distinct modes (single-market and basket) with specific verbs ('checks', 'walks the ladder', 'returns') and clearly distinguishes from sibling tools polymarket_arbitrage and polymarket_edges by stating when to use this 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 states when to use ('before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'), explains the risk of skipping it (partial fills convert arb into unhedged direction), and gives required parameter combinations.

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

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

The description goes well beyond annotations by detailing response structure (leg-by-leg prices, spread array), safety fields (compatibility_warning conditions, temporal_alignment, skipped counters), and edge cases (e.g., what matched_pairs=0 means). It also clarifies that 'pre-mapped ≠ tradeable,' setting accurate expectations. No contradictions with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint).

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

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

The description is relatively long but each sentence adds meaningful information. The first sentence establishes the purpose, followed by a logical flow: modes, response, safety fields. It could be slightly more terse, but given the complexity of the tool (cross-venue spread with many edge cases), the length is justified.

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 three parameters, no output schema, and detailed annotations, the description is remarkably complete. It explains the response structure, safety fields, temporal alignment, and when spreads are meaningful. It addresses potential user confusion (e.g., 'pre-mapped ≠ tradeable') and covers edge cases 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?

Schema covers 100% of parameters with descriptions, giving baseline 3. The description adds value by explaining the override behavior (explicit tickers override topic-mapped side) and providing the exhaustive list of topic shortcuts, which goes beyond the schema's brief 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 computes 'cross-venue spread between Kalshi and Polymarket for the same resolving question,' specifying the verb ('compute spread'), resource (two prediction markets), and scope (matching question). It distinguishes itself from sibling tools like polymarket_arbitrage (intra-venue) and polymarket_edges (single-venue edge detection) by focusing on cross-venue comparison.

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

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

The description explains two modes (topic shortcuts and explicit pairings), provides examples, and warns that pre-mapped topics often produce compatibility warnings, implying the tool is best used when a known matching event exists or when exploring macro topics with caution. It does not explicitly contrast with sibling tools, but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context about scoping to an identifier and the pairing with remember/forget, enhancing the agent's understanding 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?

Every sentence serves a purpose: the first states the primary action, the second explains usage, the third details scoping, and the fourth links to sibling tools. No redundancy or 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?

Given the simplicity of the tool (one optional parameter, no output schema, clear annotations), the description covers all relevant aspects: purpose, usage context, behavioral traits, and relationship to other tools. No gaps remain.

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

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

The input schema describes the 'key' parameter with 100% coverage. The description adds semantic meaning by providing examples of what keys represent (e.g., ticker, address) and explaining the behavior when omitted, which goes 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 uses specific verbs ('retrieve', 'list') and identifies the resource ('value previously saved via remember', 'all saved keys'). It distinguishes from siblings by naming remember and forget, and clarifies the dual behavior based on argument presence.

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

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

The description explicitly states when to use ('to look up context the agent stored earlier') and how it avoids re-deriving information. It mentions scoping and companion tools, but does not explicitly state when not to use the tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds context about the returned data (source, citation_uri, raw payload), filtering capabilities, and the mark_read behavior that affects future calls. No contradictions.

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

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

The description is informative and front-loaded with the main purpose. Each sentence adds value, though it is slightly lengthy. It could be more concise by omitting the mention of the alternative endpoint, but it remains focused.

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

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

Given no output schema, the description adequately explains return fields (source, citation_uri, raw payload). All parameters are covered by schema descriptions. The annotations cover safety and idempotency. The tool's use case (polling alerts) is well-supported, including mention of an alternative REST endpoint.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema by explaining the effect of mark_read (flags events as read for next call) and noting that since expects an ISO timestamp. It also gives an example for type (e.g., 'sec_8k'). Not all parameters are explicitly described in text, but key ones are.

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 pulls fired events from a subscription feed and returns recent alerts, which is a specific verb+resource combination. It distinguishes from siblings like list_subscriptions by focusing on event retrieval rather than subscription management.

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

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

The description explains when to use the tool (pull alerts) and mentions that polls work fine, as well as an alternative GET endpoint for scripts/dashboards. However, it does not explicitly state when not to use it or provide a comparison with siblings like search_within.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds behavioral detail: fans out to three sources, handles rate limits, and provides return structure. No contradictions.

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

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

Single paragraph but efficiently packed with information. Front-loaded with examples and purpose. Could arguably be split into sections but remains clear and concise.

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

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

No output schema, so description covers return structure (changes[] grouped by source, total_changes, citation URIs). Also notes API sunset and fallback behavior. Covers edge cases well.

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

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

Schema coverage is 100% but description adds meaning: explains 'type' is limited to 'company', 'since' accepts ISO or relative shorthand with examples, 'value' is ticker or CIK. Provides usage context beyond schema.

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

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

The description opens with example queries and clearly states 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It explicitly distinguishes from sibling tool 'entity_profile' which is for static profiles.

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

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

Provides explicit context on when to use (dynamic changes) and when not to (use entity_profile for static profiles). Also explains fallback logic (GDELT→GNews) and notes soft-failure for USPTO.

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

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

Adds behavioral details beyond annotations: persistence duration (24 hours for anonymous, persistent for authenticated users), scoping by identifier, and idempotent nature. 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?

About six sentences, front-loaded with purpose, covering when, how, persistence, and linking to siblings. Almost every sentence adds value; slightly longer than strictly necessary but still 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?

For a simple key-value memory tool with full schema coverage and detailed annotations, the description covers purpose, usage, behavior, persistence, and sibling relationships completely.

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

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

Schema coverage is 100% and already describes key and value with examples. The description adds minimal new semantics beyond confirming they form a key-value pair.

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: 'Save data the agent will need to reuse later' and distinguishes it from siblings by mentioning recall and forget. It provides specific verb and resource.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and explains why. It also guides pairing with recall and forget, offering clear context and alternatives.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds that each call cascades through multiple internal lookups, replacing 2-3 manual steps, and details supported types and returned data elements, providing behavioral context beyond annotations.

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

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

Description is front-loaded with representative queries, uses bullet points for supported types, and every sentence adds value. It is dense but well-organized, earning 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?

Despite no output schema, the description fully explains return fields and structures. It covers both entity types with input formats and internal behavior, leaving no gaps for a lookup tool.

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

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

Schema coverage is 100%, and the description enriches each parameter with concrete examples (e.g., ticker, CIK, brand/generic names) and explains the return format for each type, adding significant 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 resolves user-spoken names to canonical IDs, with specific verbs and resource. It distinguishes itself from siblings by positioning as the first step for ID lookups, contrasting with tools like 'entity_profile' that likely provide broader information.

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

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

Description explicitly advises 'Use FIRST whenever you have a name but need an ID' and provides example queries for when to invoke. It lacks explicit exclusions or alternatives, but the usage context is clear and practical.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds significant behavioral context: it probes each entity internally, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, signal density. 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 three sentences, each serving a purpose: function statement, process explanation, and use case with output. No wasted words, front-loaded with primary action.

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

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

Given the tool has 4 parameters (1 required) and no output schema, the description adequately explains the return format (ranked list with score, confidence, signal density). It also clarifies the first entity is treated as the 'subject' for narrative. Annotations cover safety. Sibling tools are listed. The description is complete for this complexity level.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description does not add extra detail beyond the schema; it mentions 'your brand + N competitors' which is implicit from the entities array. No new parameter semantics are provided, 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?

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check internally, and ranks results. This distinguishes it from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison). The verb 'scan' and resource 'competitor AI presence' are specific and unambiguous.

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

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

The description provides a concrete use case: competitive AI-marketing audits, and gives an example question. It implies this tool is for multiple entities, but does not explicitly exclude single-entity usage or mention alternatives. The sibling list includes ai_visibility_check for single probes, which is a natural alternative, but not contrasted.

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

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

The annotations already declare readOnlyHint and idempotentHint, but the description goes beyond by detailing the return structure (summary block, per-advisory detail, links, alternative versions) and disclosing potential timing issues ('bundlephobia's first measurement... can take 5-30s') and how failures are reported.

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 at about 5 sentences, with the core purpose front-loaded. Every sentence adds new information, but there is minor redundancy (e.g., 'NPM ecosystem only' is repeated in both context and fallback). Still, well-structured overall.

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 (composite check across multiple sources, partial failures), the description is complete: it lists all return fields, explains failure behavior, and notes version ranges. With no output schema, the description fully conveys what the agent can expect.

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

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

The input schema covers both parameters with descriptions (package and version). The description adds useful context: scoped packages are accepted, and version defaults to latest when omitted. This adds value beyond the schema, though schema coverage was 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 starts with 'Composite should I add this npm package to my project check in ONE call', clearly stating the tool's purpose with a specific verb and resource. It also distinguishes itself from siblings by explicitly noting the NPM-only scope and directing to alternative tools for other ecosystems.

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

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

The description explicitly states when to use the tool: 'Use whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. It also provides guidance on alternatives for non-NPM packages and mentions graceful handling of partial failures.

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 safe, idempotent read operation. Description adds technical details: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation flag, and return of character offsets and similarity scores.

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

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

Single, well-structured paragraph with purpose first, then usage, then technical details. Every sentence adds value, no redundancy.

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

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

No output schema, but description explains return format (passages with offsets and similarity scores). Also covers input limits and truncation behavior. Sufficient for an intelligent agent to use correctly.

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

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

Schema coverage is 100% but description adds meaningful context: default and range for limit, example queries for query, and max size for text. Provides more than schema alone.

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

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

Description clearly states the tool performs semantic search inside a fetched record. It provides concrete examples (SEC 10-K, article) and distinguishes itself from sibling tools like ask_pipeworx_grounded.

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

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

Describes when to use (record too big for prompt) and what to pass (text + query). Mentions pairing with ask_pipeworx_grounded, but does not explicitly state when not to use.

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

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

The description provides good behavioral context: authentication needs, delivery channels, rate limits. However, it contradicts the idempotentHint annotation by implying each call creates a new subscription without mentioning idempotency. This reduces transparency.

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

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

The description is detailed but not overly verbose. Information is front-loaded with purpose. Some structure could be improved but it is efficient overall.

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 authentication, types, parameters, delivery channels, and rate limits. Lacks detail on idempotency and return value behavior, but is comprehensive for a creation tool.

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

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

Schema coverage is 100%, and description adds significant value by providing concrete examples for each type and detailed delivery options. This goes beyond what the schema alone offers.

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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It distinguishes itself from siblings like list_subscriptions and unsubscribe by focusing on creation.

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 examples for each subscription type and parameter structure, and notes requirement of Pipeworx OAuth account. It does not explicitly state when not to use, but context from siblings implies 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?

While annotations already indicate read-only, idempotent, and open-world, the description adds value by explaining the output structure (category-bucketed examples) and the effect of the topic parameter. It does not contradict annotations.

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

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

The description is front-loaded with example queries and clearly structured. It is slightly verbose but every sentence is informative, no redundancy.

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

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

Given the simplicity of the tool and rich annotations, the description covers purpose, usage, parameters, and output nature comprehensively. It explains the return format (category-bucketed questions with tool shapes) without needing an output schema.

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

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

The schema only has one parameter with basic description; the description expands by listing example topic values and explaining the behavior difference when omitted or provided, adding significant context beyond schema.

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

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

The description clearly states the tool's purpose: to suggest example questions for Pipeworx, returning category-bucketed examples with tool shapes. It distinguishes itself from siblings like ask_pipeworx by focusing on onboarding and idea generation.

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

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

Explicitly advises to use this tool first when unsure what Pipeworx can do, and specifies when to use no arguments versus a topic filter. It implies alternatives are the direct query tools, providing clear 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?

Adds significant context beyond annotations: ownership enforcement, deactivation vs deletion, and preservation of historical events. 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?

Two sentences, 34 words, front-loaded with action, no redundancy. Every sentence adds value.

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

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

For a single-parameter tool with no output schema, the description covers purpose, constraints, behavioral impact, and links to related tool (recent_alerts). Complete for its complexity.

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

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

Schema coverage is 100% with description of 'id' as subscription uuid. The description repeats 'by id' but adds no new meaning beyond what schema already provides. 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?

Clearly states the action 'Cancel a subscription by id' and distinguishes from siblings by mentioning ownership enforcement and deactivation vs deletion.

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 mentions ownership constraint (only your own subscriptions) and behavioral note (deactivated, not deleted), providing context for when to use and hinting at recent_alerts for history. No explicit alternatives but sufficient guidance for a simple tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral details: the fast path for financial claims via SEC EDGAR + XBRL with exact percent-delta math, the grounded pipeline for other claims, and the verdict types returned. This enhances transparency 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 packed with information in a single paragraph, front-loaded with examples. All sentences contribute value, but it's slightly dense and could benefit from more structured formatting (e.g., bullet points) for readability.

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 return values (verdict types, actual value with citation, reasoning), explains the dual pipeline behavior, and highlights efficiency gains. It is complete for the intended use case.

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

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

Schema coverage is 100%, so baseline is 3. The description adds nuance: tolerance_pct overrides implied tolerance, is capped at 5, and can be set to 1-2 for hallucination detection. The claim parameter is illustrated with examples, adding context beyond the schema description.

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

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

The description clearly defines the tool as a natural-language claim verifier against authoritative sources. It provides examples of trigger phrases ('Is it true that…', 'fact check') and specifies the two distinct pipelines for company-financial claims versus other claims, differentiating it from sibling tools like ask_pipeworx_grounded.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It details the two pipelines based on claim type but does not explicitly exclude usage scenarios or compare to alternatives like ask_pipeworx_grounded, leaving some ambiguity.

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