disease

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that the default model is Workers AI Llama-3.3-70b (free) and that `_apiKey` is passed straight through to Anthropic. This goes beyond annotations without contradicting them.

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

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

The description is four sentences, each adding value. It is front-loaded with the core action and use cases, and every sentence earns its place. No wasted words.

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

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

Given the tool has 4 parameters, no output schema, and no nested objects, the description explains the return format (per-model {score, confidence, signals, raw_response} + combined view) and multiple use cases. It is complete enough for an AI agent to invoke correctly, though it does not detail the meaning of 'confidence' or 'signals'.

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 all parameters have descriptions. The description adds context: default model for `models`, BYO key explanation for `_apiKey`, example entities for `entity`, and disambiguating use of `context`. This adds significant meaning beyond the schema.

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

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

The description uses a specific verb ('probe ... and score') and identifies the resource ('what they know about a business / brand / product / topic'). It clearly distinguishes from sibling tools by focusing on AI visibility scoring for marketing audits, pre-launch checks, and competitive monitoring.

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

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

The description clearly states use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to provide `_apiKey` and the `models` parameter. It does not explicitly exclude alternatives among siblings, but the context of sibling names (e.g., `scan_competitor_ai_presence`) implies differentiation.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive behavior. The description adds transparency by explaining the internal routing to 3,751 tools, citation URIs, and return of structured answers. No contradiction; description enriches behavioral understanding.

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 front-loads the key guidance ('PREFER OVER WEB SEARCH'). It is concise but dense with examples and details. Every sentence adds value, though it could be slightly shorter by grouping examples.

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 query tool with simple input and no output schema, the description covers what, when, and how it works (routing, sources, citations). It lacks details on error handling or rate limits, but for an agent to select and invoke correctly, it is sufficiently complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the scope of questions (real-world entities, events, numbers) and giving examples, which helps the agent formulate appropriate questions beyond the schema's parameter names.

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

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

The description explicitly states the tool routes questions to 3,751 tools across 886 verified sources for structured data with citations, and distinguishes itself from web search. The verb 'ask' and resource 'Pipeworx' are clear, with many examples of query types (SEC filings, FDA data, etc.).

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 strong guidance to prefer over web search for factual, data-driven questions and provides specific query patterns ('what is', 'look up', 'find', etc.). It does not explicitly state when not to use it, but the examples and emphasis on authoritative structured data imply appropriate usage. Contrast with sibling tools is minimal, but the intent is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds critical behavioral context: it costs one extra LLM call, returns a structured response with explicit refusal reasons (not_in_source, no_tool_match, etc.), and emphasizes it uses only the tool result. This goes well beyond the annotations.

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

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

The description is moderately long but front-loaded with the core purpose ('Hallucination-resistant answer mode'). Every sentence adds value: routing details, return structure, refusal reasons, usage guidance. It's well-structured with a clear flow, though slightly verbose for a concise ideal.

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

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

Given the tool's complexity (multiple aliases, complex return behavior, no output schema), the description is complete. It explains the full response payload (answer, evidence, confidence, source, errors) and refusal cases. It also covers the one-key parameter and provides sufficient context for an agent to use it correctly.

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

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

Input schema has 100% coverage: all parameters are aliases for 'question' with descriptions. The description adds no new parameter meaning beyond stating 'Your question in natural language.' Baseline 3 is appropriate since schema covers everything; description doesn't enhance semantics.

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 a 'hallucination-resistant answer mode for high-stakes reads.' It distinguishes itself from ask_pipeworx by explaining it extracts answers strictly from tool results, preventing invented facts. The specific verb 'extracts' and resource 'tool result' make the purpose precise.

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 advises when to use: 'when an answer will be quoted, cited, or acted on, and the agent must not invent facts' (e.g., financial verdicts, legal claims). It also tells when not to use: 'prefer ask_pipeworx for casual lookups.' This provides clear use vs. alternative guidance.

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

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

The description is exceptionally transparent, detailing tool behavior beyond annotations: fan-out examples, response shapes, resolver contract, parent_event extractor, news fields, safety mechanisms, wide-spread warnings, and resolution-rule risk. Annotations indicate readOnly and idempotent, which are corroborated.

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

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

The description is lengthy but well-structured with sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) and front-loaded with the core purpose. While verbose, the detail is necessary for correct usage of a complex tool, earning a 4.

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

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

Given no output schema, the description fully explains return fields (market, analysis, evidence, etc.), safety mechanisms, and edge cases. It covers all necessary context for an agent to use the tool correctly, making it complete.

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

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

Schema coverage is 100%, and each parameter has a description in the schema. The tool description adds context about how parameters are used (e.g., market input formats) but does not significantly enhance semantic understanding beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison). It distinguishes from sibling tools like polymarket_edges by focusing on a single bet 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 provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' While it doesn't explicitly state when not to use or mention alternatives, the use cases are clear and relevant.

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 significant behavioral context: data source (SEC EDGAR/XBRL), handling of off-calendar fiscal years, sorting by primary metric, and return type (paired data + 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 front-loaded with examples and the key 'ALWAYS PREFER' directive. It packs substantial detail without being overly verbose. One could argue it's slightly long, but every clause adds value (trigger phrases, data sources, behavior, output). A 4 reflects good conciseness with minor room for tightening.

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

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

For a tool with no output schema, the description fully covers what the agent needs: purpose, entity types, data sources, sorting, output format (paired data + citations), and efficiency benefit. It compensates for the lack of output schema by explaining return structure. This is complete for its complexity.

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

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

Input schema has 100% description coverage: type (enum with description) and values (array with min/max items and per-type examples). The description adds no parameter-level detail beyond what the schema provides, but it does reiterate the distinction between company and drug values. Baseline 3 is appropriate since schema already does the work.

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

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

The description explicitly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs in one parallel call. It provides trigger phrases (e.g., 'X vs Y', 'rank these companies') and distinguishes between two entity types with distinct data sources (SEC EDGAR for companies, FAERS for drugs). This clearly differentiates it from sibling tools like entity_profile or get_historical.

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

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

The description gives explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It explains it replaces 8-15 sequential lookups, making the efficiency case clear. It also details what each type retrieves (company: 10-K financials; drug: FAERS counts), helping the agent decide.

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: decomposes sub-questions, parallel routing, returns verbatim evidence with citations and gaps, time estimate (15-60s), account requirement. 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 packed with valuable information but is somewhat long; however, every sentence adds value, and it front-loads the core function. Slight bonus for efficiency.

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, behavior, parameters, output format, prerequisites, and time estimate comprehensively. No output schema, but description adequately describes returns.

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

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

Schema coverage is 100%, but description adds meaning: explains depth options (quick=3, standard=5, thorough=8), notes thorough requires paid plan, and advises question format (broad/multi-part).

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 multi-source research by decomposing questions, routing to many tools in parallel, and returning grounded answers with citations. It distinguishes itself from siblings like ask_pipeworx, which is for single 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?

Explicitly says to use for broad/multi-part questions and recommends ask_pipeworx for single lookups. Also notes account and paid plan requirements for thorough depth.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to repeat safety. However, it adds valuable behavioral context about the output: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' This goes beyond annotations in describing the response format.

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 (~100 words) and well-structured: first sentence states purpose, then usage guidance, then output details, and finally a call to action. Every sentence is informative with no redundancy.

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

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

Given the tool's complexity (6 parameters but only 1 required), full schema coverage, and no output schema, the description covers purpose, when to use, and output format thoroughly. It provides enough context for an agent to decide to call it and 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?

Schema coverage is 100%, so parameter descriptions exist. The description adds marginal semantic value by listing example query domains (SEC filings, financials, etc.), but the schema already covers aliases and purpose. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides specific examples of use cases (e.g., SEC filings, financials) and distinguishes itself from sibling tools by positioning itself as a discovery tool that returns tool definitions ready to call.

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

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

The description explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear guidance on when to use the tool, implying it should be used before other tools to identify the right one.

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 show readOnlyHint, idempotentHint, openWorldHint. The description adds valuable details: fans out across multiple sources, patent API sunset soft-fail, news fallback GDELT→GNews, and return fields. 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?

The description is slightly long but well-structured: starts with examples, then key instruction, then detailed output. Every sentence is informative, but could be slightly tightened without losing 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?

Despite no output schema, the description details all return fields (cik, company_name, filings, fundamentals, patents, news, LEI) and limitations (patents soft-fail, name unsupported). It fully addresses the tool's complexity.

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

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

Schema coverage is 100% with good descriptions, but the description adds nuance: ticker or CIK format, names not supported, and clarifies the enum type. 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 clearly states the tool provides a 'full cross-source profile of a US public company' and includes many synonyms like 'Tell me about X', 'company profile for Microsoft'. It explicitly distinguishes itself from sibling chaining tools, making it easy for an AI to select.

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

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

The description provides explicit 'when to use' with example queries and says 'ALWAYS PREFER over chaining single-pack...'. It also gives an alternative: 'use resolve_entity first if you only have a name', which is excellent 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 destructiveHint=true, so the description's 'Delete' aligns. However, it adds minimal extra behavior beyond the annotations, such as clarifying the type of data to delete.

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, purpose stated first, usage guidance second. Every sentence adds value with no superfluous content.

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

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

For a simple delete operation with one required parameter and no output schema, the description covers purpose, usage, and relations to siblings. It could mention behavior on missing keys, but overall complete.

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

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

Schema coverage is 100% for the single 'key' parameter, and the description does not add additional meaning beyond what the input schema provides. Baseline score 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 states 'Delete a previously stored memory by key' which is a specific verb and resource. Among siblings like 'remember' and 'recall', it clearly distinguishes itself as the deletion counterpart.

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 the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. Also mentions siblings 'Pair 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 (readOnlyHint, idempotentHint, destructiveHint) already indicate safe, idempotent behavior. The description adds value by detailing the process: fetches page, extracts title/description/key links, emits standard llms.txt format. No contradictions with annotations.

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

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

The description is a single paragraph that front-loads the purpose and includes specific output details. It is efficient with no wasted words, though slightly verbose with examples that could be integrated more concisely.

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 2 parameters and no output schema, the description covers purpose, process, and output format completely. No missing context needed for agent to select and invoke correctly.

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

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

Schema coverage is 100%, with both parameters (url, max_links) documented in schema. The description mentions 'extracts ... key links' but does not elaborate on max_links parameter. Since schema fully covers parameters, description adds minimal extra meaning beyond what schema provides.

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

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

The description clearly states the verb 'generate' and resource 'llms.txt file', and specifies the target URL. It distinguishes itself from sibling tools like 'scan_competitor_ai_presence' by focusing on file generation rather than scanning or checking.

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: getting a client's site indexed, drafting for own project, or auditing competitors. This provides clear context for when to use, though it does not explicitly state when not to use or 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 read-only, idempotent, and non-destructive. The description adds the return fields (cases, deaths, etc.), providing useful context beyond annotations. 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?

One sentence with examples, no wasted words. All information is front-loaded and easy to parse.

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

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

Given the low complexity (one param, output schema exists) and rich annotations, the description is complete. It explains what the tool does and what it returns, sufficient for correct invocation.

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

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

The schema covers the parameter fully with examples and description. The tool description merely restates that it is for a specific country, adding no new meaning beyond the schema.

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

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

The description clearly states the tool checks COVID-19 stats for a specific country and lists the returned fields. It distinguishes from siblings like get_global_stats (global) and get_vaccine_stats (vaccine-specific) by focusing on country-specific 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 implies use for a specific country but does not explicitly state when to use it over alternatives or provide exclusion criteria. The examples help, but comparative guidance is missing.

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 discloses specific data fields returned, adding value beyond annotations (readOnly, idempotent, non-destructive). No contradiction. Provides context on scope (worldwide) but does not mention pagination or rate limits, which are less relevant here.

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, front-loaded sentence with no fluff. Immediately states purpose and lists returns. Efficient and well-structured.

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

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

Given low complexity (0 params, 100% schema coverage, annotations present, output schema exists), the description is complete. Provides all necessary information for an agent to select and invoke correctly.

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

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

Tool has no parameters; schema coverage is 100%. Description does not need to explain parameters but adds value by specifying output fields. Baseline for 0 params is 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?

Description clearly states the tool checks worldwide COVID-19 totals and lists specific returned data (cumulative cases, deaths, recovered, active, today's new cases and deaths). Distinguishes from sibling tools like get_country_stats and get_historical by specifying 'worldwide'.

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 vs alternatives. However, the name and description imply it's for a quick global overview, and sibling tools exist for more granular data. Lacks 'when-not-to-use' or alternative suggestions.

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. Description adds that data is returned by date and includes cases, deaths, recoveries, but offers no further behavioral details (e.g., update frequency, limits). Minimal value added beyond annotations.

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

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

Two sentences, no fluff, front-loaded with verb and resource. Every word 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 tool with two optional parameters, full annotations, and an output schema, the description sufficiently covers core functionality. Could mention date format or granularity but not necessary for clarity.

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. Description adds context about country or global scope but does not enhance parameter understanding beyond schema. Baseline 3 is appropriate.

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

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

Description clearly states the tool retrieves daily COVID-19 timeline data for a country or globally, specifying the return of historical progression of cases, deaths, and recoveries. This distinguishes it from sibling tools like get_country_stats which likely provide current stats.

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 historical timeline data but does not explicitly compare with alternatives like get_country_stats or get_global_stats. No guidance on when to use this tool versus others.

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, etc.), description adds key behavioral detail: returns cumulative doses over the past 30 days. 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?

Two sentences with no wasted words. Front-loaded with purpose and scope, concise yet complete.

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 1 optional param and output schema. Description covers return type (cumulative doses daily over 30 days), sufficient for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds that omitting country gives global totals, consistent with schema. No additional semantic depth 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?

Clearly states the verb 'Check' and resource 'COVID-19 vaccination progress' with scope (country or globally). Distinct from sibling tools like get_country_stats and get_global_stats.

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 indicates when to use (check progress for a country or globally) and explains the country parameter. Lacks explicit when-not or alternative tools, but context is clear.

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

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

Annotations already declare readOnly and idempotent. Description adds that it lists 'active' subscriptions by default and details returned fields, but doesn't add significant behavioral depth beyond annotations.

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

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

Two sentences, no extraneous information. First sentence states action and output, second gives usage advice.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers purpose, output fields, and usage context.

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

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

Schema coverage is 100% with description of include_inactive. Description doesn't mention the parameter, so no added semantics 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?

Clearly states it lists active subscriptions, specifies returned fields (id, type, etc.), and distinguishes from sibling tools like subscribe/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 says to use it for reviewing monitoring before adding or to find an ID to cancel, providing clear context. Lacks explicit alternatives but sufficient.

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 beyond annotations: rate-limited to 5 per day, free, doesn't count against quota. Annotations are neutral (no destructive/readonly hints), and description adds clarity without contradiction.

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

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

Description is detailed but every sentence earns its place. Front-loaded with purpose, then usage, then constraints. Could be slightly more concise but 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?

No output schema needed (simple action). Description covers input requirements, usage guidance, and constraints (rate limit, quota). Complete for its complexity.

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

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

Schema coverage is 100%, but description adds context for each parameter: explains enums like bug/feature/data_gap, describes context fields (pack, tool, vertical), and message format. Adds value 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 sends feedback about bugs, features, data gaps, or praise. It distinguishes from sibling tools (which are data retrieval/analysis) by being the only feedback tool.

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

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

Explicitly states when to use: for broken tools, missing tools, or praise. Also specifies what not to do (don't paste end-user prompt). Could mention alternatives but uniqueness makes it sufficient.

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

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

Annotations provide read-only, idempotent, non-destructive info. Description adds 'self-aggregating signal', 'no PII', and caching behavior (5min-1h), which are useful beyond what annotations convey.

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 short, front-loaded sentences with zero waste. Each sentence serves a purpose: functional description, use cases, and technical 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?

For a simple read-only tool with one optional parameter and no output schema, the description fully covers behavior and output (top tools, packs, count). Caching and privacy are addressed.

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

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

Schema covers all parameters (100% coverage). Description adds context on window semantics: 'Shorter windows surface what's hot right now; longer windows show steady-state demand', enhancing schema description.

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

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

Description starts with a clear statement: 'Returns the top tools, top packs, and total call volume over a recent window'. It uses specific verbs and resources, and distinguishes from other sibling tools which don't cover trending.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming canonical choice, aligning use case). Does not provide when-not-to-use, but the tool's read-only nature makes misuse unlikely.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds extensive behavioral context: how event mode works (walks child markets, checks ordering, computes partition_check), how topic mode works (cross-event scanning, semantic anchor, partition filter), and details on the fill check. 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 lengthy but every sentence provides necessary detail. It is front-loaded with the critical requirement (REQUIRES one of event or topic). However, some redundancy and density could be trimmed without losing 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, the description thoroughly explains the response structure (opportunities with gap_pp, suggested_trade, etc.) and edge cases (placeholder filters, fill check). It covers the tool's complexity well 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?

The input schema already has 100% coverage with descriptions for both parameters. The description adds significant value by explaining the semantics of event slug vs URL, topic as a seed question, and the different modes. This enriches the schema beyond basic descriptions.

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

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

The description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks. However, it does not explicitly differentiate itself from sibling tools like polymarket_edges or polymarket_edge_tracker, which may have overlapping functionality.

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 that one of 'event' or 'topic' is required, and explains when to use each mode. It also provides guidance on when not to trade via the fill check, and mentions custom sizing with another tool. This is comprehensive and clear.

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

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

Annotations indicate read-only, idempotent, open-world. Description adds extensive behavioral details: three model families with calculations, edge derivation, slippage, cache duration, diagnostics, and Fed bet exclusion. 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?

Description is dense but well-structured with numbered segments and knobs. Every sentence adds value. Slightly verbose due to technical detail, but appropriate 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?

Despite no output schema, description thoroughly explains response structure (by_segment, fed_candidates, diagnostics), return fields, and caching. Given the tool's high parameter count and complexity, the description provides nearly complete context.

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

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

All 9 parameters have schema descriptions (100% coverage), earning a baseline of 3. The description adds practical guidance beyond schema (e.g., min_liquidity example value, slippage context), justifying a higher 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?

Description clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' identifying the verb, resource, and purpose. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_kalshi_spread by focusing on Pipeworx-driven edges.

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

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

Explicitly states use case 'what should I bet on today' and explains response segments. While it does not directly compare to sibling tools, the purpose and filtering knobs provide clear context. Lacks explicit 'use this when' vs 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 (readOnlyHint, idempotentHint) are consistent. The description adds valuable behavioral details: snapshots written on cache-miss causing gaps, 60-day TTL, decay from daily closes not intraday. 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?

The description is well-structured and front-loaded with purpose, but slightly lengthy. Every sentence adds value, though it could be trimmed without losing 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?

Given no output schema, the description thoroughly explains return fields (tracked[], expired[], snapshot_dates[]) and limitations (TTL, decay computation). Complete for a complex 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%. The description adds marginal context (e.g., 'lookback' for days, 'snapshot family' for window) but does not significantly extend schema meaning.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question about edge longevity and distinguishes itself from sibling tools like polymarket_edges by focusing on temporal tracking.

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

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

The description provides context on when to use the tool (e.g., distinguishing fresh vs old edges) and explains the output structure (tracked[], expired[], snapshot_dates[]), but does not explicitly mention alternatives or when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. Description adds substantial behavioral context: returns detailed fill diagnostics, warns about partial basket fills converting arb into directional position, and explains what the tool checks internally (walks ladder, calculates slippage, etc.).

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 relatively long but well-structured with clear sections for single-market and basket modes. Uses bold headings and bullet-style lists. Every sentence adds value; some redundancy could be trimmed but overall effective for a complex tool.

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

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

Given the tool's complexity (two modes, four parameters, many return fields, no output schema), the description is remarkably complete. It lists all return fields for both modes, specifies parameter defaults and constraints, and explains the behavioral consequences of partial fills. Leaves no gaps for agent understanding.

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 meaning beyond schema: explains side default behavior in basket mode (auto based on partition sum), interprets size_usd differently for single-market vs basket (settlement notional), and clarifies clamping range. Enhances understanding of parameter behavior in different modes.

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 checks realizable-vs-theoretical edge against live CLOB depth, distinguishes single-market and basket modes, and specifies return fields. Contrasts with sibling tools like polymarket_arbitrage by saying 'use this before acting on' those signals.

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

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

Explicitly requires one of market or event, explains when to use each mode, and provides direct usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', with rationale about theoretical overround not being capturable and risk of partial basket fills.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds extensive behavioral details: two operational modes, safety fields (compatibility_warning, temporal_alignment, skipped counters), and explicit cases where spreads are invalid. Fully transparent beyond annotations.

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

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

Description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). Front-loaded with purpose. Minor redundancy in explanation of compatibility_warning, but each sentence contributes necessary detail for a complex tool.

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

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

Given the tool's complexity, no output schema, and multiple edge cases, the description covers all critical aspects: response structure (leg-by-leg prices, matched spreads), safety fields for non-equivalent bets, temporal alignment, and skip counters. Sufficient for an agent to understand behavior and avoid pitfalls.

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

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

Schema coverage is 100%, but description adds significant meaning: explains that 'topic' is a pre-mapped macro shortcut with specific values, and that explicit tickers override the topic-mapped side. Gives examples and clarifies that most pre-mapped topics currently return compatibility_warning. Adds value 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 explicitly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly identifies the tool's verb and resource, and distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

Explains two modes (topic shortcuts and explicit tickers) and provides warnings when spreads are not meaningful (compatibility issues, temporal misalignment). However, it does not explicitly compare to sibling tools like polymarket_edges or define when to use this over other spread-related tools.

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

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

Disclosure of scoping to identifier (anonymous IP, BYO key hash, account ID) adds transparency beyond annotations. Annotations already declare readOnly, idempotent, and non-destructive, which description confirms without contradiction.

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

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

Compact single paragraph with no filler. Every sentence serves a purpose: retrieval behavior, use case, scoping, and related tools. Highly 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?

Covers main use cases and scoping. Without output schema, description implies return of value or key list, which is sufficient for a simple retrieval tool. Could mention output format but not critical.

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

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

Schema has 100% coverage for the single optional 'key' parameter. Description adds practical guidance: omit to list all keys and typical key values (ticker, address, notes), enhancing semantics 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 retrieves saved values by key or lists all keys, with concrete examples like 'user's target ticker' or 'address'. It distinguishes from siblings '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?

Provides explicit use case: looking up context stored earlier without re-deriving. Mentions pairing with remember/forget, implying alternatives. Lacks explicit when-not-to-use 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructuctiveHint=false. The description adds valuable context: the returned fields, the effect of mark_read on subsequent calls, and that polling is supported. 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 concise and well-structured. It front-loads the main purpose, then provides important details (returned fields, filtering options, mark_read behavior, polling support, alternative endpoint). Every sentence adds value without redundancy.

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

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

Given the 5 parameters, no output schema, and rich annotations, the description provides sufficient context: what the tool returns, how to filter, the effect of mark_read, and an alternative access method. It could briefly mention default limit (50) or unread_only behavior, but these are covered in the 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?

All 5 parameters have descriptions in the schema (100% coverage), so the baseline is 3. The description adds meaning by explaining the filtering usage of 'type' and 'since', and the behavioral effect of 'mark_read'. It does not add detail for 'limit' or 'unread_only', but schema already covers them.

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

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

The description clearly states the tool pulls fired events from a subscription feed and returns recent alerts with specific fields (source, citation_uri, raw payload). It distinguishes the tool's focus on subscription alerts, but does not explicitly differentiate from siblings like 'list_subscriptions' or 'recent_changes'.

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

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

The description implies usage for fetching and filtering alerts, and mentions that polling works fine and that the same feed is accessible via a separate endpoint for scripts/dashboards. However, it does not provide explicit when-to-use or when-not-to-use guidance relative to sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context: fan-out pattern, fallback behavior (GDELT→GNews on rate limit/5xx), USPTO soft-fail, output format (grouped changes, total_changes, citation URIs). No contradictions.

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

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

Single dense paragraph that front-loads purpose, then details sources and params, then provides sibling differentiation. Every sentence serves a purpose—no wasted words. Highly 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?

Despite no output schema, the description sufficiently describes the return structure: 'Returns structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs.' Also addresses failure modes (USPTO soft-fail, GDELT rate limit fallback). Complete enough for an AI agent to understand behavior.

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

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

Schema coverage is 100% for all three parameters. The description adds meaning beyond schema: explains 'since' accepts ISO date or relative shorthand with examples ('7d', '30d', '3m', '1y') and recommends '30d' or '1m'. Explains 'value' accepts ticker or CIK. This extra context justifies a score above baseline 3.

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

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

The description clearly states the tool provides a change feed for a company over recent time, fanning out to multiple sources (SEC EDGAR, GDELT/GNews, USPTO). It gives concrete examples like 'What's new with X' and explicitly distinguishes from sibling tool entity_profile, which provides static profiles.

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

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

Provides explicit when-to-use examples ('What's new with X', etc.) and when-not-to-use guidance: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' Also explains fallback logic for GDELT→GNews and USPTO soft-fail.

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 behavioral details beyond annotations: key-value storage, scoping by identifier, persistent memory for authenticated users, 24-hour retention for anonymous sessions. This complements the annotations (idempotentHint=true, destructiveHint=false) without contradiction.

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

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

The description is three sentences, front-loaded with purpose, then usage guidelines. No extraneous 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?

Given the simple key-value store with good annotations and full schema coverage, the description is complete. It covers scope, persistence, and related tools.

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

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

Schema coverage is 100% with clear descriptions for both 'key' and 'value'. The description adds example key naming conventions, but the schema already provides detailed parameter info. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It uses a specific verb ('Save') and resource ('data'), and distinguishes from sibling tools ('recall', 'forget') by mentioning 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 explicitly tells when to use: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also provides context about authentication scoping and mentions related tools for retrieval and deletion.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds that each call cascades through several lookup endpoints, providing additional behavioral context without 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, starting with example queries and then detailing usage, types, and results. Every sentence is useful, though slightly verbose in the supported types section.

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

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

Despite lacking an output schema, the description fully explains what is returned for each entity type (including citation URIs), making the tool's behavior complete and predictable.

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

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

Schema coverage is 100%, and the description significantly enriches both parameters by providing examples, accepted formats, and explaining what identifiers are returned for each type, adding 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 starts with concrete example queries and clearly states the tool resolves a name to a canonical identifier. It specifies supported entity types and distinguishes itself from sibling tools by advising 'Use FIRST whenever you have a name but need an ID.'

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 tells when to use the tool ('whenever you have a name but need an ID') and mentions it replaces multiple manual lookups. However, it does not explicitly list alternative tools or conditions where it should not be used.

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 fully discloses behavioral traits: probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, and signal density. Annotations (readOnlyHint, idempotentHint) are consistent; 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?

The description is concise (3 sentences), front-loaded with the main action, and every sentence adds information without redundancy. 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?

Despite no output schema, the description clearly explains the return format (ranked list with score, confidence, signal density per entity). Annotations cover safety. The tool is moderately complex, and the description is complete.

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

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

Schema coverage is 100%, and all parameters have descriptions. The description adds semantic value by noting that the first entity is treated as the 'subject' and the rest as competitors, which is not in the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using the verb 'compare' and specifying the resource (AI visibility). It distinguishes from the sibling tool ai_visibility_check (single entity) by mentioning 'across multiple entities' and 'Probes each entity (your brand + N competitors)'.

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

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

The description provides explicit usage context: 'Useful for competitive AI-marketing audits: does Claude know about us as well as our competitors?' It implies when to use this tool (multi-entity) versus the single-entity sibling. However, it does not explicitly state when not to use or list all 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?

Discloses that it fans out across services, that bundlephobia's first measurement can take 5-30s, and that partial failures degrade gracefully with sources_failed listed. Adds significant value beyond annotations.

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

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

All sentences are informative, no fluff. Structured logically: purpose, usage, constraints, failure mode. Front-loaded with core composite capability.

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 complex composite tool, it covers ecosystem scope, version handling, failure behavior, and return structure. No output schema but description compensates fully.

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 context beyond schema: accepts scoped packages, version defaults to latest, and explains return summary. Schema coverage is 100%, and description enriches parameters.

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

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

The description clearly states it is a composite check for npm packages across deps.dev and bundlephobia, with specific outputs like license, advisories, bundle size, etc. It distinguishes itself from sibling tools by its unique purpose.

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

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

Explicitly says when to use: when agent asks about safety, popularity, size, or cost. Also specifies NPM only in v1 and mentions partial failure behavior, providing 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 read-only, idempotent, non-destructive. Description adds algorithmic details (BGE-base-en, cosine, 500-char windows), char limit (200K with truncation flag), and output format (passages with offsets and 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?

Two sentences cover purpose, usage, algorithm, limitations, and output. No redundant information; every clause 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 no output schema, description explains return values (passages, offsets, scores). Algorithm and truncation are covered. Could mention if any text format constraints (e.g., plain text only) but generally complete.

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

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

Schema covers all parameters with descriptions. Description adds context: text examples and query examples, plus limit default/range. Enhances understanding beyond schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, and provides examples (SEC 10-K, article). It mentions pairing with ask_pipeworx_grounded but does not explicitly differentiate from siblings like 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?

Explicitly says to use when the record is too large for the prompt, saving context. Suggests pairing with ask_pipeworx_grounded. Does not state when not to use or compare directly with other search tools.

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

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

Adds rich behavioral details beyond annotations: subscription persistence, OAuth requirement, delivery channel limitations (SMS cap, webhook auto-disable), and one-time webhook secret. Annotations indicate idempotent and non-destructive, which description supports.

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 front-loaded purpose sentence. Examples and details are valuable but could be slightly more compressed. Reasonable length for a subscribe tool with multiple 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?

Covers all essential aspects: purpose, prerequisites, parameter details, return value, and constraints. No output schema, but description adequately explains the return. Complete for a moderate-complexity 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 already covers 100% of parameters. Description adds examples and constraints for each parameter type and delivery channel, providing practical context 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?

Description clearly states verb ('Create'), resource ('proactive monitoring subscription'), and output ('Returns the new subscription id'). Distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation.

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

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

Explicitly states prerequisite (requires Pipeworx OAuth account) and limitation (anonymous + BYO cannot persist). Provides guidance on delivery channels and constraints, but no explicit when-not-to-use or direct comparison with alternatives.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context about being an onboarding entry point, returning categorized examples, and drawing from a live catalog. 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 thorough but slightly verbose, front-loaded with synonyms/questions. Every sentence adds value, but could be tightened. Still, it remains clear and well-structured.

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

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

Given the low complexity (1 optional param, no output schema), the description fully explains purpose, return structure, when to use, and how to focus. No gaps remain for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with one optional parameter described. The description adds meaning by explaining the effect of omitting the argument (full spread) and providing example values for topic (finance, pharma, betting), which enhances understanding beyond the schema list.

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

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

The description explicitly states the tool returns category-bucketed example questions with exact tool+argument shapes, serving as an onboarding entry point. It distinguishes itself from siblings like discover_tools and ask_pipeworx by specifying context of first-time usage.

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

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

The description provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also lists alternatives like ask_pipeworx, entity_profile, etc., and explains the optional topic parameter for focus.

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 explains deactivation vs deletion and references recent_alerts for historical events. This complements annotations (destructiveHint: false, idempotentHint: true) without contradiction.

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

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

Two efficient sentences that front-load the core action and then add important constraints and behavior. 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?

For a simple tool with one param and no output schema, the description covers purpose, ownership, deactivation behavior, and relationship to recent_alerts, making it fully complete.

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

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

Only one parameter (id) with schema coverage 100% and description 'Subscription id (uuid) returned by subscribe.' Description does not add extra meaning beyond what the schema provides, so baseline 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?

Description clearly states 'Cancel a subscription by id', specifying verb and resource. It distinguishes from siblings like 'subscribe' (create) and 'list_subscriptions' (list) by focusing on cancellation.

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

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

It provides clear context: 'Ownership is enforced — you can only cancel your own subscriptions.' This implies usage when you own the subscription, but no explicit when-not or alternative tool guidance is given.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructive behavior. The description adds valuable behavioral context: the return format (verdict, structured form, actual value with citation, percent delta), the supported scope (company-financial via SEC EDGAR + XBRL), and the fact that it's a composite tool replacing multiple steps. No contradiction with annotations.

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

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

The description is a single paragraph that is well-organized: it starts with examples and usage, then explains scope and output. It is not overly verbose, but it could be slightly more structured (e.g., bullet points) for readability. Every sentence contributes meaning.

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

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

Given the simple input (one parameter) and no output schema, the description fully explains what the tool returns (verdict, structured form, citation, delta). It covers the supported claim domain and limitations. The tool's complexity is low, and the description provides 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 input schema has 100% coverage with a parameter description including examples. The tool description further clarifies the natural-language format by example and specifies the type of claims (company-financial). This adds value beyond the schema alone, justifying a score above the baseline of 3.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources for company-financial claims. It provides specific examples ('Is it true that...') and outlines the supported claim types (revenue, net income, cash position). This distinguishes it from sibling tools like deep_research or get_historical, which serve different purposes.

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 advises using the tool 'whenever the agent needs to check whether something a user said is factually correct.' It also notes that it replaces 4-6 sequential calls, implying efficiency. However, it does not provide explicit when-not-to-use guidance or directly name alternatives among siblings, though the limitations to financial claims are implied.

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