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 already mark it read-only and open-world; the description adds valuable behavioral context by revealing that the tool routes to one of 5,798 source tools, fills arguments automatically, and returns stable pipeworx:// citation URIs. It does not contradict the annotations and makes the internal routing and citation behavior visible.

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 and well organized, but it is repetitive: 'even if web search could also answer it' appears twice, and 'START HERE for most questions' restates the earlier prefer-over-web-search guidance. The examples earn their place, but a tighter edit would improve it.

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

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

The description is complete for an open-world, read-only Q&A tool: it lists domains, gives trigger phrases, supplies examples, explains the routing behavior, and describes the return format as a structured answer with citations. Given the lack of an output schema, a short note on fallback behavior when no source matches would make it fully 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?

With 100% schema coverage, the schema already documents the 'question' parameter and its six aliases. The description adds value through concrete query patterns and domain examples, and by saying the tool 'fills arguments' it signals that the caller only needs to supply a high-level natural-language question.

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

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

The description clearly states a specific function: accept a natural-language question, route it to one of thousands of tools, and return a structured answer with pipeworx:// citations. It is far more specific than the name, but it does not explicitly differentiate itself from sibling tools such as ask_pipeworx_beta or ask_pipeworx_grounded.

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

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

The description gives explicit when-to-use guidance: prefer this over web search for factual, current, or historical questions, with trigger phrases like 'look up', 'find', 'current', and it supplies concrete examples. It does not state when not to use it or how to choose among the ask_pipeworx_* sibling variants.

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/openWorld/idempotent/destructive safety, so the description adds value by disclosing that this is a live-test edge, currently matches the stable router, and that results may be compared to decide merges. The 'falls back to nothing — this IS a full working router' line usefully corrects a likely misconception.

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 compact paragraph with no filler: it states identity, current behavior, intended use, and fallback semantics in four sentences. The most decision-relevant fact, that it currently matches ask_pipeworx exactly, appears early, though the sentence about the retirement date is slightly more detail than strictly needed.

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 the schema covering parameters and annotations covering side effects, the description supplies the remaining usage state: identical to ask_pipeworx, no active candidate, and full functionality without fallback. It does not detail the stable sibling's behavior or the exact response format, but 'same response shape' keeps it complete enough 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 the schema fully documents the six parameters. The description repeats that the tool takes the same arguments but adds no semantic detail beyond the schema, matching the baseline for 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 identifies ask_pipeworx_beta as an experimental universal router that mirrors ask_pipeworx exactly, with candidate routing improvements when active. It is specific enough to separate it from grounded/research siblings, though the core action is mostly implicit in the name and context rather than a strong standalone verb.

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

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

It explicitly tells the agent to use it exactly like ask_pipeworx when the newest routing is desired, and clarifies the current no-candidate state. It does not explicitly enumerate when NOT to use it, but the comparison to the stable router and mention of the experimental edge provide adequate routing guidance.

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

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

Discloses rich behavioral detail beyond the readOnly/openWorld/idempotent annotations: the precise success return shape with evidence and confidence, the explicit refusal reasons enum, and the grounding constraint that the answer must come only from the tool result. 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 front-loaded with the core differentiator ('Hallucination-resistant answer mode for high-stakes reads') and every subsequent sentence adds concrete value: routing, extraction behavior, return/refusal formats, usage guidance, and cost trade-off. No filler or redundancy.

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

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

Despite lacking an output schema, the description fully specifies the success and refusal response structures, enumerates refusal reasons, explains routing and grounding behavior, and gives clear usage boundaries. An agent has everything it needs to decide when to invoke this tool and what to expect.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no additional parameter-level meaning beyond what the schema already provides for the 'question' parameter and its aliases. It is acceptable because the schema carries the full 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 this as a hallucination-resistant, grounded answer mode that extracts answers exclusively from tool results. It differentiates itself from ask_pipeworx by the grounded extraction and evidence requirement, making the purpose and distinction unambiguous.

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

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

Explicitly states when to use this tool (answers that will be quoted, cited, or acted on; situations where facts must not be invented) and when to prefer the alternative (casual lookups), while naming ask_pipeworx as the sibling with the same routing. This gives an agent clear routing logic.

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 already declare read-only, idempotent, open-world, non-destructive behavior, and the description adds substantial depth: account/tier requirements, facet decomposition, parallel tool routing, gaps[] for unanswered questions, citations that are always fetchable, contradictions[] for standard/thorough, semantic excerpting, and latency expectations. This meaningfully complements the structured annotations.

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

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

The description is longer than average, but it is dense and front-loaded: auth, fallback, core purpose, and top use case appear first, with behavioral and latency details after. Some phrasing is slightly awkward, but nearly every sentence contributes non-redundant, decision-relevant information.

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

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

For a two-parameter tool with no output schema, the description is remarkably complete: it explains what the tool processes, how it decomposes questions, what the returned findings packet contains, how missing data is handled, what citations mean, and how long calls take. No essential selection or invocation context 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 already solid. The description goes further by explaining what each depth tier costs and does, how 'thorough' differs from 'standard,' and what kind of question is appropriate for the question parameter, including concrete examples. That adds real value beyond the schema.

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

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

The description states a precise action ('Grounded multi-source research') and names the exact resource domain: Pipeworx's 1517 structured data sources across SEC, FRED/BLS, FDA, USPTO, and more. It explicitly distinguishes the tool from open-web search and from sibling ask_pipeworx, so an agent can reliably tell when deep_research is the right 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?

It gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data.' It also gives a clear exclusion: 'For a single lookup use ask_pipeworx instead,' and handles the auth prerequisite with 'If you are not signed in, use ask_pipeworx.' This leaves almost no ambiguity about routing.

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?

Annotations declare readOnly/openWorld/idempotent, and the description adds substantial behavioral detail beyond them: fan-out across multiple data sources, soft-failure of the USPTO patents API after May 2025, expected empty results for FDA products with small-molecule drugs, resolved:false for private companies, and sources_used/sources_failed semantics. No contradiction exists between the description and annotations.

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

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

The description is long and dense, but it front-loads the core purpose and usage examples before diving into return-field details. It is a single wall of text rather than structured sections, which slightly hurts scanability, yet every sentence carries meaningful behavioral or selection information. Some repetition with the schema, such as type accepting both values, is minor.

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?

Because there is no output schema, the description carries the full burden of explaining return shape, and it does so thoroughly: CIK, resolved fields, recent filings, fundamentals, patents, federal contracts, FDA products, hiring, news, and LEI. It also covers failure modes and expected empty sections, making it sufficiently complete for an agent to invoke the tool correctly and interpret results.

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

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

Schema coverage is 100%, but the description still adds meaningful parameter context: value can be a ticker, zero-padded CIK, or company name; names resolve via SEC EDGAR's company-name match; and type accepts 'company' or 'ticker' interchangeably. It reinforces the schema with examples and clarifies normalization behavior, which is genuinely helpful for an agent.

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

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

The description opens with concrete example queries and a precise statement: 'full cross-source profile of a US public company in ONE parallel call.' This names the resource (US public companies), the action (profile), and the scope (cross-source, parallel). It also explicitly positions itself against chaining single-pack lookups, which helps distinguish it from sibling tools even though it does not name them.

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

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

The description gives explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' and supplies many concrete trigger phrases. It also explains edge-case usage, such as what happens for private companies and how to pass tickers, CIKs, or names. This is strong, actionable routing guidance.

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

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

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?

Annotations are all false and offer little, so the description carries the full burden. It discloses several behavioral traits beyond the schema: filing without an account returns a claim_token for later status retrieval, rate-limit of 5 per identifier per day, free/no quota cost, and that the team reads digests daily. No contradiction with annotations exists.

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

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

The description is dense but every sentence earns its place. It opens with purpose, then usage, exclusion, content guidance, token workflow, rate limits, and cost—all in a compact, ordered structure. No filler or repetition.

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

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

Given the tool's moderate complexity (conditional token flow, exclusion rules, rate limiting), the description covers all necessary aspects: purpose, exact trigger scenarios, boundaries, token handling, and operational details. No output schema exists, but the description sufficiently explains expected return behavior (claim_token and later status).

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context for the claim_token parameter (explaining the full workflow: filing returns a token, passing it back later reads status) and for message content (don't paste end-user's prompt). This elevates parameter 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 opens with a clear, specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates exact use cases (bug, feature/data_gap, praise) and clearly differentiates this feedback tool from sibling research/query tools like ask_pipeworx or deep_research.

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

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

Explicit when-to-use guidance is provided ('Use when a tool returns wrong/stale data...'), along with a strict when-not-to-use boundary ('ONLY for tools served by this Pipeworx connection') and an alternative action ('file it with that server instead'). It also gives content guidance ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt').

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?

Annotations already mark the tool read-only and idempotent, and the description adds substantial behavioral context beyond that: compatibility codes, the rule that 'unknown' legs are never paired, the meaning of null in temporal_alignment, the gross-vs-net fee disclosure, and skipped comparison counters. All of this is consistent with the annotations and significantly improves agent decision-making.

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

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

The description is long and dense, but it is well-structured with clear sections for modes, response, safety fields, and counters. The front-loaded purpose and mode explanation help an agent get oriented quickly. Minor redundancy exists, such as repeatedly emphasizing that both modes behave identically, but the complexity of the tool justifies most of the length.

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

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

With no output schema and a complex response, the description carries the full burden of explaining return semantics. It covers compatibility warnings, per-entry flags, unclassified legs, temporal alignment semantics, fee treatment, and skipped counters. The agent is given enough information to interpret results correctly and to understand limitations like unverified pairings.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value by explaining that `kalshi_event_ticker` and `polymarket_event_slug` 'override the topic-mapped' side, and by enumerating the exact pre-mapped topic values. It also clarifies that both modes share the same matching behavior, which is not evident from the schema alone.

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

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

The description opens with a specific function, 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which clearly identifies the tool's core purpose. It also distinguishes the two operating modes, but it does not explicitly contrast this tool with sibling tools like polymarket_arbitrage, so it stops short of full sibling differentiation.

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

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

The description gives concrete when-to-use guidance by explaining the two modes: pre-mapped `topic` shortcuts versus explicit `kalshi_event_ticker` + `polymarket_event_slug` custom pairings. It also warns that 'pre-mapped ≠ tradeable' and that most topics currently return compatibility warnings, which helps an agent avoid misuse. It does not name alternative tools or state explicit exclusion conditions.

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 declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds substantial context beyond this: graceful degradation when GLEIF/OpenFIGI is unavailable, ambiguous matches returning figi_candidates instead of asserting, explicit unresolved identifier reporting, cascading internal lookups, and source-labeled identifiers. No contradiction with annotations.

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

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

The description is long, but it is well organized with front-loaded user-phrase examples, a clear 'Use FIRST' directive, and a SUPPORTED TYPES section. Some detail is verbose, but most sentences earn their place given the tool's complexity and lack of an output schema.

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

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

With no output schema, the description carries the burden of explaining return behavior, and it does so: figi_candidates for ambiguous matches, an explicit unresolved field, source-labeled identifiers, RxCUI citation, and degradation behavior. It also covers input constraints, edge cases, and supported entity types, making it sufficient for correct selection and invocation.

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

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

Schema description coverage is 100%, but the description goes well beyond schema by giving exact input semantics: pass only the entity name, never the full noun phrase, with bond examples and reasons why trailing security-class words fail. It also enriches the type enum with resolution behavior for company and drug, including ISIN-to-LEI mapping and RxCUI 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 states a specific verb and resource: resolving user-spoken names to canonical/official identifiers for company and drug entities. It is thorough and distinguishes its role as a first-step ID resolver, but it does not explicitly name sibling tools such as entity_profile or compare_entities, so sibling differentiation relies on inference.

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 guidance: 'Use FIRST whenever you have a name but need an ID,' and it lists many natural-language triggers. It does not state when not to use this tool or name alternative tools, so it stops short of a full 5.

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

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

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?

Beyond annotations (read-only, idempotent), the description discloses the two execution paths (SEC EDGAR vs grounded), the exact verdict categories returned, and warns that `could_not_verify` means the check did not happen and must not be treated as evidence. It also clarifies the difference between `unsupported` and `could_not_verify`. This adds substantial behavioral context beyond what annotations provide.

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

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

The description is long but every sentence earns its place: it opens with practical trigger phrases, defines the two pipelines, enumerates return values, explains important caller warnings, and ends with an efficiency note. It is well-structured and front-loaded with the most actionable information.

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

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

Despite having no output schema, the description fully covers return values (verdicts, evidence, reasoning), error cases (`could_not_verify` with `verification_error`), and source coverage (`unsupported`). It is self-contained for a complex tool with two execution paths, making it complete for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100% with clear descriptions for both `claim` and `tolerance_pct`. The description adds nuance about `tolerance_pct`, explaining the default behavior ('implied by wording, capped at 5') and its use for hallucination detection ('set 1–2'), which enriches understanding of parameter semantics beyond the schema.

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

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

The description clearly identifies the tool's purpose: natural-language claim verification against authoritative sources, with explicit trigger phrases like 'Is it true that…' and 'fact check'. It distinguishes from sibling tools by focusing on verifying claims rather than general Q&A or research, and highlights that it consolidates 4–6 sequential steps into one call.

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

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

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further differentiates the fast path for company financial claims and the grounded pipeline for any other factual claim, covering essentially all cases. The description implies no exclusions, making the usage context comprehensive.

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