Deno Land

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds useful behavioral context: it probes LLMs, returns per-model results, and mentions cost (free default, Anthropic requires user-provided key and pays Anthropic directly). 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, front-loaded with the core purpose. The second sentence adds model details, and the third gives use cases. No wasted words; every sentence earns its place.

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

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

The tool has no output schema, but the description explains the return structure (per-model score, confidence, signals, raw_response + combined view). It covers purpose, parameters, usage, and output format. Minor gaps: no details on combined view or confidence scoring, but overall sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the default model, the purpose of _apiKey (BYO key for Anthropic), and that context disambiguates entities. This extra context justifies a 4.

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

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

The description clearly states the tool's function: probing LLMs for AI visibility and scoring (0-100). It specifies the resource (LLMs), action (probe, score), and outcome (per-model scores + combined view). It distinguishes itself from sibling tools like ask_pipeworx by targeting brand/product visibility audits rather than general Q&A.

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

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

The description gives clear context on when to use: for AI-marketing audits, pre-launch brand checks, competitive monitoring. It clarifies model options (default free Workers AI, optional Anthropic with BYO key) and cost implications. However, it does not explicitly exclude alternatives or state when not to use 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?

The annotations already establish a safe read-only, idempotent profile. The description adds meaningful behavioral context beyond that: it routes the question to one of 5,596 tools, auto-fills arguments, and returns stable pipeworx:// citation URIs. It does not detail failure modes or exact response structure, but for a read-only tool the annotations cover the main risk surface.

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 front-loads the important 'prefer over web search' message and is organized into clear parts. However, it's long, with an exhaustive domain list and example queries that largely duplicate the schema examples. Some redundancy toward the intended length without losing clarity.

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

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

For a tool with no output schema, this description covers the core purpose, usage triggers, and provides several concrete examples. Yet it does not explain what the structured answer looks like, how failures or unsupported questions are handled, or when a sibling variant might be more appropriate. Those gaps are notable but not performance-limiting for a router-type tool.

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

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

Schema coverage is 100%, with the 'question' parameter clearly described and its aliases listed. The description's examples reinforce intended input but don't add new semantic information beyond the schema. An agent can safely invoke the tool from the schema alone, so a baseline 3 is appropriate.

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

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

It clearly names a specific verb and resource: route natural-language factual questions to authoritative, verified data sources and return structured answers with citation URIs. The description is specific enough to understand what the tool does without opening the schema. However, it doesn't differentiate from the sibling tools ask_pipeworx_beta and ask_pipeworx_grounded, so purpose clarity is strong but not fully distinct.

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 over web search, use for factual queries about real-world data, trigger phrases like 'what is', and examples of when web search could also answer. It also says 'START HERE for most questions.' However, it does not mention alternative sibling tools like deep_research or ask_pipeworx_grounded, so exclusions are incomplete.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: it may enable candidate routing improvements live, currently matches ask_pipeworx because no candidate is active, and remains a fully working router rather than a fallback stub.

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 identity and explains candidates, current state, usage, and redundancy in a compact set of sentences. It is somewhat repetitive in stating 'identical'/'same' multiple times, but for an experimental variant of a broad router the detail is justified.

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

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

Given the absence of an output schema, the description sufficiently explains behavior, current parity with the stable tool, and how to invoke it. It relies on the sibling ask_pipeworx for detailed response semantics, and does not explicitly describe return-value format, but the statement 'same response shape' mitigates that gap.

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

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

The input schema covers all parameters with 100% description coverage, including the required question and its aliases. The description adds no additional parameter-specific meaning beyond saying arguments are identical to ask_pipeworx, so it meets the baseline without exceeding schema-provided information.

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

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

The description explicitly identifies the tool as the beta version of ask_pipeworx, a universal router with the same 5,596 tools, same arguments, and same response shape. It clearly distinguishes the experimental routing behavior from the stable ask_pipeworx sibling.

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

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

The description says to use it 'exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It does not explicitly state a when-not-to-use case, but the contrast with stable ask_pipeworx makes the intended tradeoff clear.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses the confident grounded-only behavior, the exact success return shape with evidence quoted, the explicit refusal shape with all five refusal reasons, and the cost of an extra LLM call. It also states that the tool will refuse rather than guess, which is material behavioral context.

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

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

The description is dense and information-rich, and every sentence contributes purpose, behavior, cost, or usage guidance. It loses only a little structure points because there is a long clause about the exact routing scale before the more decision-critical behavioral details.

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

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

There is no output schema, so the description compensates by specifying the success payload, refusal payload, refusal reasons, and cost trade-off. Combined with complete schema coverage and annotations, an agent has enough context to decide whether to use this tool and what to expect from it.

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

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

Schema description coverage is 100%, so the schema already carries the parameter payload. The description adds that the question is in natural language and that the tool fills route/flush arguments automatically, but it does not need to add more since the schema already documents question and aliases.

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

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

The description states a specific verb and resource: it is a grounded mode that routes a question to the right tool, fetches the data, and extracts an answer using only the tool result. It also explicitly differentiates itself from ask_pipeworx by its resistance to hallucination and its refusal behavior, so the agent can distinguish the two without opening either schema.

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

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

The description gives explicit when-to-use guidance: use for answers that will be quoted, cited, or acted on, or when facts must not be invented, and name concrete domains such as financial verdicts, legal claims, medical lookups, and public statements. It also tells the agent to prefer ask_pipeworx for casual lookups due to the extra LLM call cost.

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 exhaustively discloses behavioral traits beyond the annotations. It details fan-out mechanics, classifier categories, resolution confidence handling (high/medium/low/none), closed market detection, wide spread warnings, resolution-rule risk (cancellation rules), and edge case behavior. This far exceeds the minimal read-only/idempotent annotations. No contradictions with annotations are present.

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 (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It front-loads the core purpose and usage in the first two sentences. While every sentence adds value, the description could be more concise by trimming examples. However, given the tool's complexity, the current level of detail is appropriate for an AI agent.

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

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

The description covers all necessary context for the tool's operation: input formats, classifiers, fan-out sources, response structure, resolver contract, parent event extraction, news field fallback, safety mechanisms, and resolution-rule risk. There is no output schema, so the description fully compensates. The level of detail ensures an agent can correctly select and invoke the tool without ambiguity.

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

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

The input schema has 100% description coverage, so the baseline is 3. The description adds significant behavioral context: explaining how the 'market' parameter accepts different formats, how 'depth' (quick vs thorough) affects fan-out, and the 'include_raw' flag's impact on response size. While the schema already covers basic semantics, the description provides deeper insight into operational behavior, justifying a score of 4.

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

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

The description clearly states 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), the action (research via data pull), and acceptable input formats (slug, URL, question text). It also provides usage examples ('should I bet on X'). This level of specificity effectively distinguishes the tool from siblings like polymarket_edges or polymarket_arbitrage, which focus on edge detection or arbitrage rather than comprehensive 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?

The description explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear context for when to invoke the tool. However, it does not provide explicit when-not-to-use guidance or directly compare with sibling tools. The implicit differentiation from siblings like polymarket_edges and polymarket_arbitrage is present but not spelled out, which prevents a higher score.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description details exact data sources per type: company pulls 10-K financials (revenue, net income, cash, debt) from SEC EDGAR/XBRL with correct fiscal year handling; drug pulls FAERS adverse events, FDA approvals, trial counts. It also explains result sorting and output includes citation URIs. 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 information-dense with no wasted words, starting with trigger phrases and then explaining functionality. However, it is fairly long and could benefit from structured formatting (e.g., bullet points or sections) for easier 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?

For a tool with two types and no output schema, the description adequately covers input parameters, data sources, and output structure (paired data with citation URIs). It does not detail exact output fields, but the description is sufficient for an agent to understand what to expect.

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

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

The description adds significant meaning beyond schema: for type='company', it specifies which financial metrics are returned (revenue, net income, cash, long-term debt) and mentions correct handling of off-calendar fiscal years. For type='drug', it mentions specific data (FAERS, FDA approvals, trials). Schema coverage is 100% but description enriches semantics substantially.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call. It lists trigger phrases ('compare X and Y', 'X vs Y') and distinguishes itself from siblings like entity_profile (single-entity lookups) and sequential alternatives.

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

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

The description explicitly recommends preferring this tool over sequential lookups when comparing entities. It implies usage for financial or drug comparison based on type. However, it does not specify when not to use (e.g., for non-financial/non-drug comparisons or single-entity queries), leaving some ambiguity.

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

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

The description goes well beyond the annotations: plan/account requirements, parallel routing, explicit gaps[], contradictions[] only in certain depth modes, resolvable citation_uri semantics, semantically excerpted records, and latency expectations. There is a clear picture of what side effects look like without contradicting the readOnlyHint/openWorldHint/idempotentHint annotations.

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

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

The definition is long but justified by the tool's complexity and covers everything from auth to latency. It is reasonably well organized and front-loads the critical auth/fallback caveats, but has repetitive references and a somewhat awkward 'BREAKING' clause that make the prose feel less polished.

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?

Even without an output schema, the description leaves no gaps in selecting and execution: findings packet composition, gaps[], contradictions[], citation_uri fetchability, depth behavior, paid plan requirements, latency expectations, and unsupported use-case todos. The caller knows what to expect and what to avoid.

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 already 100% and thoroughly documents both question and depth with enum meanings. The tool description adds some value (paid plan nuance, why depth is defined, broad question tolerance) but mostly repeats the schema's existing depth semantics rather than providing substantially new parameter-level insight.

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

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

States a precise resource and action: 'Grounded multi-source research... across Pipeworx's 1,465 STRUCTURED data sources', 'Decomposes your question into focused facets, routes each to one of 5,596 tools in parallel, and returns a findings packet'. It also explicitly distinguishes itself from open-web search, making the tool's identity 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?

Gives explicit when-to-use / when-not-to-use guidance: use ask_pipeworx when not signed in, when doing a single lookup, or for breaking live-news topics; use deep_research for broad multi-part questions over structured data. It also warns that topics outside the structured catalog return mostly empty gaps[], helping the agent avoid misuse.

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 non-destructive. The description adds 'Best-effort', which is a useful behavioral hint indicating potential incompleteness. However, it does not disclose failure modes or edge cases (e.g., what happens if version is not found). The transparency is adequate but not exceptional.

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, concise, and front-loaded with the core action. Every word serves a purpose, with no redundancy. It is optimally sized for quick consumption.

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 presence of an output schema (which reduces the need to describe return values) and annotations covering safety, the description is minimally complete. However, for a tool that lists dependencies, details about scope (e.g., transitive vs direct) or reliability (best-effort) could be more explicit. The description leaves some uncertainty about the nature of the list.

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 0%, so the description must compensate. It says 'from version metadata' which implies inputs are a name and version, but does not explain what valid values are or any constraints. The output schema exists (not shown) which may help, but for parameter semantics, minimal value is added beyond the schema's required fields and examples.

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

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

The description clearly states that the tool provides a dependency list ('list of dependencies') using version metadata. It uses 'Best-effort' which implies incompleteness, distinguishing it from the sibling 'scan_dependency' which likely does a thorough scan. However, it could be more specific about what exactly is returned (e.g., list of dependency names and 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?

No explicit guidance on when to use this tool versus alternatives like 'scan_dependency'. The term 'Best-effort' hints at a quick check vs. exhaustive scan, but the description does not articulate this distinction or provide any when-to-use or when-not-to-use information.

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 and idempotentHint. Description adds behavioral info: returns top-N most relevant tools, includes full schemas with examples, results are callable directly. 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?

Description is several sentences but each serves a purpose: states core function, lists example data sources, explains return format, and advises when to call. No wasted words.

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

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

Covers purpose, usage guidance, and return format (tool names, descriptions, schemas). No output schema but description explains output adequately. Sufficient for a discovery tool.

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

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

Schema coverage is 100% with good descriptions for all 6 parameters. Description only reiterates the query concept without adding new semantics, so it adds minimal 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?

Description clearly states 'Find tools by describing the data or task' and lists specific domains (SEC filings, FDA, etc.), distinguishing it from siblings like search or search_within which search data, not tool metadata.

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 'Call this FIRST when you have many tools available and want to see the option set' and 'Use when you need to browse, search, look up, or discover what tools exist for...'. Does not explicitly exclude other scenarios but provides clear context for 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?

Disclosures add significant value beyond annotations: explains it fans out across multiple sources, notes USPTO PatentsView API sunset May 2025 with soft-fail behavior, and describes fallback from GDELT to GNews. Annotations already confirm read-only, idempotent, no destruction; description enriches with these operational details.

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 paragraph but well-structured: starts with example queries, then function, then specifics. While somewhat lengthy (~150 words), every sentence contributes value. Concision is slightly impacted by the list of return fields, but structure helps readability.

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

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

Even without an output schema, the description thoroughly explains return fields: cik, company_name, recent_filings with URIs, fundamentals sorted by period_end, patents, news with fallback, and LEI. Limitations (name support, patent sunset) are clearly stated, making it complete for a complex multi-source tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing examples ('AAPL', '0000320193'), emphasizing that names are not supported, and clarifying that type is only 'company'. This extra context justifies a 4.

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

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

The description clearly states that the tool provides a 'full cross-source profile of a US public company' across SEC, XBRL, USPTO, news, and GLEIF. It uses specific verbs and resources and distinguishes itself from siblings by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups'.

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

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

Provides explicit when-to-use signals: when user asks for a holistic view like 'tell me about X' or 'research Acme'. Also specifies when-not-to-use: names are not supported, and advises using resolve_entity first. Contrasts with alternatives by recommending this over chaining single-pack lookups.

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

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

Description states destructive behavior, consistent with annotations' destructiveHint=true. No contradictions, but adds no extra behavioral details.

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

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

Two sentences, front-loaded with main action, no fluff.

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

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

Simple tool with one param and no output schema. Description covers purpose and usage adequately.

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?

Only one parameter 'key' well-described in schema. Description adds no additional semantics beyond schema, baseline of 3.

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

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

Clear verb 'Delete' and resource 'memory by key'. Distinguishes from siblings like remember and recall.

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: context stale, task done, clear sensitive data. Mentions pairing with remember and recall.

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 indicate readOnlyHint, idempotentHint, and no destructiveness. The description adds context by explaining the fetch-and-extract process and the markdown format output, which aligns with and enriches the annotations.

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

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

The description is a single paragraph that covers purpose, usage, output, and use cases without excessive wording. It is front-loaded with the core action and provides necessary detail efficiently.

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 the output format (standard llms.txt markdown, single text blob) and how to use it. Combined with annotations, it provides a complete picture for a simple tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by contextualizing the parameters (e.g., 'Fetches the page' for url, and default/max for max_links) and explaining the output format, going 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 generates a production-ready llms.txt file for any URL, specifying the output format and target AI crawlers. It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on file generation rather than scanning.

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 lists explicit use cases (client sites, own projects, competitor audits) and mentions the output is ready for site-root placement. It does not explicitly mention when not to use, but the examples provide 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?

Annotations already declare readOnlyHint and idempotentHint. The description adds value by specifying default behavior (active subscriptions) and listing return fields. 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?

Two sentences: first defines purpose and output, second provides usage guidance. No wasted words, front-loaded.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers purpose, return fields, default behavior, and usage context adequately.

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

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

Schema coverage is 100% with a clear description for the only parameter. The description adds minor context about default active subscriptions, but does not significantly extend schema info.

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 verb 'List', the resource 'the caller's active subscriptions', and lists return fields. It distinguishes 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?

Explicitly advises to use the tool for reviewing monitored subscriptions before adding more or to find an ID to cancel, providing clear context for 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 declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds only 'metadata + latest version', which is a high-level description of the output but does not disclose edge cases (e.g., module not found, error handling) or other behavioral traits beyond the annotations.

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

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

The description is extremely concise, using only 5 words. While brevity is valued, it is so short that it omits critical information, making it less effective. It is front-loaded but insufficient.

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 presence of an output schema and annotations, the description still fails to provide complete context. It does not explain what metadata is included, the structure of the output, or any requirements for the input. The tool is simple but the description is too sparse.

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 0% schema description coverage, the description must explain the 'name' parameter, but it does not. No information is provided on what the module name should be, allowed values, or format. The schema examples imply common module names, but the description fails to clarify.

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

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

The description clearly states that the tool retrieves module metadata and the latest version, with a specific verb ('get' implied by description) and resource (module). However, it does not differentiate itself from sibling tools like 'version' or 'versions', which could cause confusion.

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 versus alternatives (e.g., 'version' or 'versions'), nor any context on prerequisites or modules that are available. The description provides no usage scenario.

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

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

The description discloses several behavioral traits not in the annotations: rate-limited to 5/day, free, doesn't count against quota, team reads digests daily, and the claim_token mechanism for later status checks. It also explains that filing without an account returns a claim_token. This goes well beyond the minimal annotations.

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

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

The description is longer than average but every sentence adds critical information: purpose, usage rules, exclusions, claim_token workflow, rate limits, quota impact, and feedback impact. It is front-loaded with the main action and then logically builds context. 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?

Given the tool's moderate complexity (4 parameters, nested object, no output schema, optional claims), the description covers everything needed: what to report, how to report, what happens after filing, and how to check status later. It also addresses edge cases like uncertainty about tool name and cross-server reports. Complete for both first-time and follow-up use.

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 substantial semantic value: it explains the claim_token parameter's usage as a follow-up mechanism ('pass the pwfb_… token that filing returned, with no other arguments'), gives guidance on message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), and clarifies the context object's role as optional structured context. This enriches the schema rather than repeating it.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from the sibling research/query tools by stating its role as a feedback channel, with no ambiguity about what it does.

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

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

Explicit usage criteria are provided: use for bugs, feature gaps, data gaps, or praise. The description also gives a clear exclusion rule (only for Pipeworx tools, not other MCP servers) and names the alternative action ('file it with that server instead'). This is exemplary when-to-use/when-not-to-use guidance.

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

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

Annotations already declare read-only, idempotent, and non-destructive. The description adds that data is self-aggregating from CF analytics-engine, no PII, and cached 5min-1h, providing useful behavioral context beyond annotations.

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

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

The description is concise (5 sentences), well-structured with a definition, use cases, and technical details. Every sentence adds value without fluff.

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

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

The description explains output, use cases, data source, and caching. However, it lacks explicit return format (e.g., structure of the returned data). Given no output schema, more detail on the shape of the response would improve completeness.

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

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

Schema coverage is 100% and already includes semantic descriptions of the window parameter. The tool description repeats the same semantic info ('shorter windows surface what's hot right now; longer windows show steady-state demand'), adding no new value.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a recent window. This distinguishes it from sibling tools like search or discover_tools by focusing on crowd-sourced trending data.

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

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

The description explicitly lists three use cases: discovering hot data sources, confirming canonical tool choice, and aligning use cases. It does not specify when not to use or contrast with alternatives, but provides clear context.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds substantial behavioral context: it performs monotonicity and partition checks, uses Jaccard similarity for cross-event pairs, filters placeholder slugs, and includes a fill check that warns if realizable_edge_pp ≤ 0 (do not trade). This goes well 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 detailed but well-organized, with a clear front-loaded purpose and logical progression through modes and sub-processes. Every sentence adds value, but the length is justified by the tool's complexity. Slightly verbose compared to minimalistic descriptions, 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?

The description covers input parameters completely (event and topic with examples and semantics), explains the response structure (opportunities array with fields, partition_check object), and details edge cases (placeholder filtering, low similarity, fill check). Despite no output schema, the description provides a thorough understanding of what the tool returns and its limitations.

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, but the tool description adds significant meaning: it explains the difference between 'event' and 'topic' modes, provides examples of valid inputs, and details the internal logic (monotonicity, partition checks, semantic anchor, partition filter). This adds 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 specific verb ('Find arbitrage opportunities') and resource ('Polymarket') with clear differentiation between three modes (trending_scan, event, topic). It distinguishes itself from siblings like polymarket_edges and polymarket_fill_risk by detailing unique methods (monotonicity violations, partition-sum checks) and providing mode-specific contexts.

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

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

Explicit guidance is provided for when to use each mode: no args for trending scan, event for a specific market (recommended), topic for cross-event scanning. It explains that cross-event mode catches patterns that single-event misses, and directs users to polymarket_fill_risk for custom sizing. This covers alternatives and 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, but the description adds extensive behavioral context: caching at KV level (1h), response structure (by_segment with diagnostics), each model family's methodology (lognormal, GDELT, partition_overround), slippage assumptions, edge calculation details, and tradeable-edge knobs. It also warns about 24h market move eating the edge.

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 very long and dense with technical details. While well-structured (purpose, segments, response, knobs, caching), it could be more concise for an AI agent to parse quickly. Every sentence is informative, but the overall length reduces readability. A shorter summary at the top would help.

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

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

Given the tool's complexity (9 parameters, three model families, detailed edge calculations), the description is comprehensive. It covers each segment's methodology, output fields (edge_pp_net, kelly_fraction, liquidity, spread, volume, 24h move warning), top-level response structure, fed candidates note, and caching. No output schema exists, so this description fully compensates.

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 well-described parameters. The description adds value by explaining the interplay between parameters (e.g., tradeable-edge knobs like min_liquidity and max_spread_pp, and min_partition_leg_kelly for partitions). It also provides rationale for defaults (e.g., slippage_pp: 0.3 for 20-50bp on Polymarket). This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarkets markets and return opportunities where Pipeworx data disagrees with market price.' It explicitly distinguishes itself as a discovery tool for 'what should I bet on today,' saving agents from paging through hundreds of markets. The three model family segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) provide detailed specificity.

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

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

The description provides clear context for when to use: for discovering opportunities based on Pipeworx data disagreement. It explains that Fed bets are surfaced but excluded from ranking, and provides diagnostic fields to understand empty results. While it doesn't explicitly exclude alternatives like polymarket_arbitrage, the detailed explanation of the tool's specific output (edge, kelly, segments) gives strong usage guidance.

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

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

The description adds significant behavioral details beyond the annotations, such as data source (daily snapshots), computation method (decay from closes), and limitations (60-day TTL, gaps due to cache misses).

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

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

The description is front-loaded with the core purpose and structured logically with sections for args, response fields, and limits. It is detailed but not excessively long given the complexity.

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

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

With no output schema, the description thoroughly documents the response structure (tracked, expired, snapshot_dates) and all relevant fields. It also covers limitations and data nuances, making it fully self-contained.

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 repeats parameter defaults but does not add new semantic information 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 provides 'Edge persistence and decay telemetry' and answers a specific question about edge duration. It distinguishes from the sibling 'polymarket_edges' by focusing on temporal analysis.

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: to analyze edge longevity and decay. While it does not explicitly contrast with alternatives, the context makes its unique purpose clear.

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

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

Description adds rich behavioral context beyond annotations: walks the ladder, returns verdict line, explains capture_ratio, thin_legs, forced_directional_risk. Warns about partial fills and unhedged positions. No contradiction with annotations.

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

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

Description is somewhat long but well-structured: purpose, requirements, two modes, returns, usage guidance. Every sentence adds value; could be slightly more concise but justified by complexity.

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

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

No output schema, but description thoroughly explains return fields for both modes, including edge cases like thin_legs and forced_directional_risk. Complete for a complex analytical 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?

Despite 100% schema coverage, description adds significant value: explains size_usd differently for single-market vs basket, side defaults (auto for basket), and clamps range. Enriches 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?

Description clearly states it's a realizable-vs-theoretical edge check against live order book depth, explicitly distinguishes single-market and basket modes, and lists specific return fields. It differentiates from siblings like polymarket_arbitrage by focusing on risk assessment before executing trades.

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 requires one of market or event, explains when to use (before arb signals or trades above $500), and provides rationale (theoretical overround on thin books not capturable, partial basket fills cause unhedged directional risk).

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 extensively discloses behavioral details beyond annotations: it explains safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype), output structure (leg-by-leg prices, spread in percentage points), and conditions that render spreads meaningless (shape mismatches, temporal gaps). This is exceptional transparency for a tool with read-only and idempotent annotations.

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

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

The description is long but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence provides necessary information for correct invocation. While it could be slightly more concise, the density of valuable detail justifies the length given the tool's complexity.

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

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

The description covers inputs, outputs, and important edge cases despite lacking an output schema. It explains the response structure (prices, spreads, warnings) and conditions affecting validity. It is nearly complete, though an explicit example output would further enhance completeness.

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

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

The description adds significant meaning to all three parameters: it lists the 10 valid topic shortcuts, explains the explicit ticker overrides, and provides example values for kalshi_event_ticker and polymarket_event_slug. Since schema coverage is 100%, the description elevates understanding far beyond the schema alone.

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

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

The description clearly states the tool computes 'cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the verb (spread calculation), resources (two prediction market venues), and distinguishes from sibling tools like polymarket_arbitrage which likely focuses on single-venue arbitrage. The two modes (topic and explicit) are clearly defined.

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 spreads are meaningful (e.g., temporal alignment, matching bet shapes) and warns that most pre-mapped topics return compatibility warnings, implying caution. However, it does not directly compare this tool to similar siblings like polymarket_arbitrage or polymarket_edges, leaving the agent to infer the most appropriate tool for single-venue analysis.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds useful context about scoping ('Scoped to your identifier') and pairing with remember/forget, without contradicting annotations.

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

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

The description is two sentences, front-loads the primary action, and eliminates all unnecessary words. 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?

Given the simple parameter schema and presence of annotations, the description adequately covers behavior, scoping, and tool relations. However, it does not describe the return format (e.g., behavior when key not found), leaving a minor gap.

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

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

Schema coverage is 100% for the single parameter 'key', with schema description already noting omission lists all keys. The description adds linkage to 'remember' but does not significantly enhance parameter meaning beyond the schema.

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

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

The description explicitly states 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument)', providing specific verb and resource. It distinguishes two modes and differentiates from sibling tools like remember and forget.

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

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

The description explains when to use the tool ('use to look up context the agent stored earlier') and how it pairs with remember/forget. It lacks explicit when-not or alternative tool usage, but the context is clear.

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

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

Goes beyond annotations (readOnlyHint, idempotentHint) by explaining that setting mark_read:true flags events as read and affects subsequent calls. Discloses return fields (source, citation_uri, payload). 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?

Four sentences, front-loaded with main purpose, followed by output details, filtering, mark_read behavior, and alternative access. No wasted words.

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

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

Covers most aspects but omits mention of 'limit' and 'unread_only' parameters in description (though schema covers them). Lacks explanation of 'unread_only' behavior. Otherwise complete for a read-only tool with annotations.

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?

Adds value beyond 100% schema coverage by providing examples for 'type' ('sec_8k') and 'since' (ISO timestamp), and explaining the functional effect of 'mark_read'. Clarifies output structure.

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 verb 'Pull' and resource 'fired events from your subscription feed'. 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?

Provides filtering guidance (type, since) and explains the mark_read flag's side effect. Mentions an alternative endpoint for scripts. Does not explicitly state when not to use, but context is sufficient for most decisions.

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 (readOnly, idempotent, openWorld) are supplemented with details about fan-out to multiple APIs, fallback behavior (GDELT→GNews), soft-fail for USPTO, and return structure (grouped changes, total_count, citation URIs). No contradiction with annotations.

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

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

Description is well-structured: front-loaded with purpose and examples, then details sources and fallbacks, then parameter specifics. 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?

Despite no output schema, description fully explains return format and sources. Covers all key aspects including fallback behavior and parameter details. Distinguishes clearly from related tool entity_profile.

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 extra context: explains since format with examples and recommendation, confirms type enum only supports 'company', and clarifies value accepts ticker or CIK. Adds meaningful 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?

Description clearly states the tool serves as a change feed for recent activity on a company, listing specific sources (SEC, GDELT/GNews, USPTO) and explicitly distinguishes from sibling tool entity_profile 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?

Explicit guidance: use for 'what's new' queries, use entity_profile instead for static profiles. Example queries are provided to illustrate typical 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 indicate idempotentHint=true and destructiveHint=false, and the description adds important behavioral details: data is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours. 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 four sentences, front-loaded with the core purpose, and every sentence adds value. No unnecessary words 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?

Given the simple parameter schema (2 required strings), comprehensive annotations, and no output schema, the description covers all necessary context: purpose, usage, pairing, and retention policy. It is fully adequate 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%, so baseline is 3. The description adds context that key and value form a key-value pair and provides examples, but does not add new semantic meaning beyond the schema's descriptions.

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

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

The description clearly states the tool's purpose: save data for reuse across conversations/sessions. It provides specific examples of what to store (resolved ticker, target address, user preference) and distinguishes itself from sibling tools like recall and forget by mentioning pairing 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 explains when to use the tool: when discovering something worth carrying forward, so you don't have to look it up again. It also recommends pairing with recall and forget for related operations. It lacks explicit 'when not to use' guidance but is clear enough.

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

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

The description reveals heavy operational detail: identifiers are source-labelled, unresolved identifiers are listed rather than omitted, LEI/FIGI enrichment falls back to EDGAR if sources are unavailable, and each call cascades through multiple lookup endpoints. These traits are not captured by the annotations and substantially enhance the agent's mental model of what happens during execution.

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 deliberately structured: it leads with natural-language triggers, then dense but organized type-specific sections. Every sentence adds operational value, though a reader must parse a lot of detail before reaching the tool's core contract. It earns its length but could be more scannable.

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

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

Given there's no output schema, the description compensates by naming all returned identifiers, the unresolved-list behavior, and graceful degradation. It also fully addresses both supported types and how inputs map to outputs, making the tool's behavior predictable without needing extra documentation.

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

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

Even though the schema describes both parameters, the description enriches them: for `type` it details each subtype's return payload (CIK/ticker/LEI/FIGI vs RxCUI/ingredient/brand), and for `value` it accepts entirely different formats per type (e.g., ISIN resolves via GLEIF to legal entity). This goes far beyond the schema descriptions and clarifies ambiguous inputs.

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 immediately anchors with user queries like 'What's the ticker for…' and states the tool 'resolve[s] a user-spoken NAME to the canonical/official identifiers.' It clearly distinguishes this from sibling tools by emphasizing it's the first step when a name needs conversion to an ID, rather than searching or profiling.

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

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

Explicit guidance is given: 'Use FIRST whenever you have a name but need an ID.' The examples clarify the exact scenarios (finding CIK, LEI, etc.). While it doesn't list explicit alternatives or when-not-to-use conditions, the directive 'FIRST' strongly implies it precedes other tools that consume IDs.

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 details the probing process, ranking, and output elements (score, confidence, signal density), complementing the annotations (readOnlyHint, idempotentHint) with step-by-step behavior. 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 concise (3 sentences), front-loaded with the primary action, and every sentence adds value. No wasted words.

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

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

The description explains the entire process, how it uses another tool, and the return format (ranked list with score, confidence, signal density), fully compensating for the lack of 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?

Schema description coverage is 100%, so baseline is 3. The description adds marginal value by reiterating the 'first entry as subject' rule and the default model, but does not significantly extend beyond the schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check and ranking by score. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison) by focusing on AI 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 gives a concrete use case for competitive AI-marketing audits and explains the subject treatment. It implicitly suggests using ai_visibility_check for single entities but does not explicitly exclude alternatives, costing a point for full explicit 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 behavioral traits beyond annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed lists timeouts. Annotations already show readOnlyHint, but description adds important timing and failure details.

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 somewhat long but well-structured: first sentence defines purpose, second gives usage, third return format, fourth ecosystem limits, fifth failure behavior. Every sentence adds value, though slightly verbose.

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

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

Despite no output schema, description details the return format (summary block, advisories, links, recent versions) and covers edge cases like partial failures and first-measurement delay. Completely adequate for the tool.

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

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

Schema coverage is 100%, so schema documents both parameters well. Description adds minimal extra meaning beyond accepting scoped packages, which is already implicit from schema. Baseline 3 is appropriate.

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

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

The description clearly states it's a composite check for adding an npm package, covering license, advisories, version history, and bundle size. It uses specific verbs and resources, distinguishing itself from related tools like 'dependencies'.

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 tells when to use: when an agent asks about safety, popularity, or cost of an npm package. Also clarifies NPM-only scope and directs other ecosystems to deps.dev:version, providing clear alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. Description adds value by specifying result limit (up to 100) and return fields, which annotations do not cover.

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

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

Single sentence conveys purpose, resource, and key details. No wasted words, though could be structured with bullet points for clarity.

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 search tool with output schema, description covers main aspects: action, resource, result limit, and return fields. Lacks sorting/pagination details but adequate for typical use.

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 0%, so description must explain parameters. It mentions 'keyword' for query but does not explain 'limit' parameter or default behavior beyond the implicit 100-result cap. Insufficient compensation for missing schema descriptions.

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

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

Description clearly states the tool searches deno.land/x modules by keyword and specifies returned fields (names, descriptions, star counts, versions). However, it does not differentiate from sibling tools like 'search_within'.

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 versus alternatives. With many sibling tools, the absence of usage context is a significant gap.

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 technical details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and return format including character offsets and similarity scores. 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?

Approximately 100 words, well-structured: purpose, use case, technical details. No superfluous sentences. Front-loaded with key 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 no output schema, description fully explains return format (passages with offsets and scores), input constraints, and embedding model. Covers all necessary context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so heavy lifting is done by the schema. Description adds value by clarifying the 200K char limit for 'text', natural-language examples for 'query', and default for 'limit'. Enhances understanding but not essential.

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 it performs semantic search inside a fetched record, gives concrete examples (SEC 10-K, article), and distinguishes from sibling tools by explaining when to use it and pairing with ask_pipeworx_grounded.

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

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

Explicitly advises when to use: 'Use when the record is too big to cram into the prompt.' Also mentions pairing with ask_pipeworx_grounded for grounding, providing 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?

Adds significant behavioral details beyond annotations: OAuth requirement, delivery channels, SMS cap (10/day), webhook signing and auto-disable. Does not explain the idempotentHint annotation, but 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?

Well-structured with examples, but somewhat lengthy. Every sentence adds value; no redundancy. Could be slightly more concise but still effective.

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

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

Covers types and delivery comprehensively given no output schema. Lacks details on error responses and full return format, but overall sufficient for agent invocation.

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

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

Schema coverage is 100%, and description enriches each parameter with detailed examples, including type-specific params and delivery sub-fields. Goes well beyond schema definitions.

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

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

Clearly states it creates a proactive monitoring subscription and returns the subscription ID. Lists supported types and distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

Provides usage context including account requirements and examples for each type. Does not explicitly state when not to use or compare to alternatives, but the context is sufficient for selection among siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: it returns example questions with exact tool+argument shapes from a live catalog, and explains the open-world hint. 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 well-structured, front-loaded with purpose and usage, then details output and parameters. Every sentence serves a purpose, and it achieves completeness without verbosity.

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 simple input schema (one optional param) and no output schema, the description covers all necessary context: input, output, use cases, and even mentions the meta-tools it teaches. It is fully adequate for an onboarding tool.

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

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

Schema coverage is 100% with one optional parameter. The description enriches the parameter meaning by listing possible topic values (finance, pharma, etc.) and explaining the effect of omission, which goes beyond the schema's generic description.

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

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

The description clearly states the tool is an onboarding entry point that returns category-bucketed example questions. It specifies the verb 'suggest' and the resource 'questions', and distinguishes from sibling tools like 'ask_pipeworx' by noting it is for learning what to ask.

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

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

Explicitly instructs to use this tool FIRST when unfamiliar with Pipeworx. Mentions alternatives like ask_pipeworx, entity_profile, compare_entities, and provides context on when to use the topic parameter vs. no arguments.

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 non-destructive and idempotent behavior. The description adds valuable context: ownership enforcement, the fact that rows are deactivated not deleted, and the impact on historical data, which goes beyond the structured fields.

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

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

Three concise sentences, each providing essential information without redundancy: purpose, ownership constraint, and behavioral nuance.

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

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

The tool has one parameter, no output schema, and robust annotations. The description fully covers usage context, behavioral traits, and parameter semantics, leaving no gaps for an agent.

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

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

Schema coverage is 100% with a clear description for the sole parameter 'id'. The description does not add extra parameter details beyond the schema, which is adequate for a baseline score.

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 verb 'Cancel' and resource 'subscription by id', distinguishes from siblings like 'subscribe' and 'list_subscriptions', and adds specificity via ownership enforcement and effect description.

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 ownership enforcement ('you can only cancel your own subscriptions') and notes that historical events remain via 'recent_alerts', implying appropriate contexts. However, no explicit alternatives or when-not-to-use scenarios 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?

The description goes well beyond the annotations (readOnlyHint, idempotentHint, etc.) by explaining the two execution paths, the full verdict taxonomy, and the crucial distinction between 'could_not_verify' (verification_error with stage/detail, not evidence) and 'unsupported' (source not found). This gives the agent the behavioral context needed to interpret results correctly.

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: it opens with example queries, states the purpose, details the two pipelines, and then explains return values and error semantics. Each sentence contributes meaningful information, and the structure is logical, though slightly dense. It remains appropriately sized for the tool's complexity.

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

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

Since there is no output schema, the description compensates by clearly listing the possible verdicts, the nature of the returned evidence (grounded/structured value with pipeworx:// citation), and the distinction between 'could_not_verify' and 'unsupported.' This is sufficient for an agent to understand what to expect and how to handle each verdict.

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

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

The input schema already provides thorough descriptions for both parameters (100% coverage), including example values and tolerance semantics. The description adds value by explaining how the claim is processed (financial vs. grounded) and mentions 'exact percent-delta math,' which helps the agent understand how tolerance_pct is applied in practice, though it does not duplicate parameter details.

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

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

The description is explicit and specific: it defines the tool as 'natural-language claim verification against authoritative sources' and contrasts it with general Q&A tools by describing its two distinct pipelines (SEC EDGAR/XBRL for financial claims, grounded pipeline for all other facts). It also notes it replaces 4–6 sequential calls, further distinguishing it from siblings like search and ask_pipeworx.

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

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

The description states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also gives clear context on how claims are routed based on type. However, it does not explicitly list when not to use the tool or mention alternative tools (e.g., general search), though the routing implies it.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description adds value by specifying the exact metadata returned (upload options, dependencies, file listings). It does not contradict annotations and provides useful behavioral context beyond the structured data.

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, direct sentence that conveys all necessary information without any fluff. It is front-loaded with the core action and quickly specifies return types.

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

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

Given the tool's simplicity, the presence of an output schema, and rich annotations, the description covers everything needed. It explains the action, required parameters, and return content, leaving no obvious gaps.

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

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

The schema has 0% description coverage, so the description must compensate. It states that both parameters are required and includes an example in the schema, but does not elaborate on format or constraints. This is barely adequate for such simple parameters, but more detail would improve usability.

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 fetches metadata for a specific deno.land/x module version, requiring name and version. It distinguishes itself from siblings by specifying that it returns upload options, dependencies, and file listings for that release, which is unique among related tools like '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 makes it clear that this tool is for a specific version (name+version required), implying it should be used when a particular version is known. However, it does not explicitly mention when not to use it or provide alternatives, though the clarity is sufficient for simple use cases.

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

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

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond annotations by noting the return format ('array of version strings in reverse-chronological order'), which is useful for the agent.

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

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

A single, front-loaded sentence that conveys the purpose, resource, and return format without any wasted words. Perfectly 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?

For a simple tool with one parameter and an output schema (returning version strings), the description covers what the tool does and what it returns. 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?

With 0% schema description coverage for the single parameter 'name', the description only says 'by name' without adding details like format, constraints, or examples. The description does not compensate for the low 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 lists all published versions of a deno.land/x module by name, with specific verb ('List'), resource ('published versions'), and scope ('by name'). It naturally distinguishes from sibling tools like 'version' and 'dependencies'.

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 retrieving version history but does not explicitly state when to use this tool over alternatives like 'version' (specific version info) or 'module'. No exclusions or when-not guidance is provided.

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