Arxiv

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds important behavioral details: cost implication for Anthropic probes, key passthrough, and the return structure (score, confidence, signals, raw_response per model). 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 three sentences, front-loaded with the core action, and each sentence adds unique information without redundancy. 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 no output schema, the description adequately outlines the return shape (per-model fields + combined view). It covers parameters and use cases. A small gap: it doesn't mention how to interpret the score or confidence, but overall it is sufficient.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining how 'models' and '_apiKey' interact (default model, optional Anthropic) and clarifies the 'context' parameter for disambiguation. This goes beyond the schema.

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

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

The description uses a specific verb ('Probe'), identifies the resource (LLMs), and defines the output (visibility score 0-100). It clearly distinguishes this tool from siblings like 'ask_pipeworx' or 'entity_profile' by focusing on AI visibility scoring.

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

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

The description explains default vs. paid model usage (Workers AI free, Anthropic with BYO key) and lists use cases (AI-marketing audits, brand checks). It does not explicitly state when not to use it or point to alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: it routes to specific tools, fills arguments, and returns structured data with stable citation URIs. This goes beyond what annotations provide.

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

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

The description is long but well-structured: front-loaded with the key directive, followed by examples and usage guidance. Every sentence adds value, though the list of data types is extensive. It achieves a good balance of completeness and clarity.

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

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

Given no output schema and a complex meta-tool nature, the description covers purpose, usage, behavior, and examples. It lacks details about error handling or unsupported queries, but overall is thorough and addresses potential agent confusion.

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 all parameters documented. The description provides examples and clarifications (e.g., aliases for 'question'), but does not add significant new constraints or format details beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool answers factual questions using authoritative structured data, with specific examples (SEC filings, FDA data, etc.) and a strong directive to prefer over web search. It distinguishes itself from web search by highlighting its routing across 3,810 tools and 909 sources.

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 to use for factual questions about current or historical data, listing specific use cases. It advises using whenever the user asks certain query types. It does not explicitly state when not to use or compare to siblings like deep_research, but the guidance 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 provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds refusal reasons, extra LLM cost, and return structure 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?

Well-structured and front-loaded with key info; every sentence adds value (use case, behavior, cost, refusal reasons).

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 high complexity, full schema coverage, no output schema (but description details output), and annotations, the description is complete and covers all necessary aspects.

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 6 parameters are aliases for question; schema coverage is 100%. Description does not add meaning beyond schema, so baseline score 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?

Description clearly states it's a hallucination-resistant answer mode for high-stakes reads, with specific verb+resource and distinct from 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 when to use (quoted/cited/acted on, must not invent facts) and suggests prefer ask_pipeworx for casual lookups.

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

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

Annotations already indicate readOnly, idempotent, non-destructive traits, and the description adds extensive behavioral details: fan-out to data sources, resolver contract, handling of closed markets, low-confidence matches, wide spreads, cancellation rules, and news fallbacks. No contradictions with annotations are present, and the description significantly enriches agent 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 lengthy (~800 words) but well-organized into clear sections (classifiers, fan-out examples, response shapes, safety, etc.). It front-loads the primary purpose. While verbose, the complexity of the tool justifies the length, and the structure aids readability. Minor conciseness improvements are possible.

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 (3 parameters, no output schema, multiple internal processes), the description is highly complete. It covers resolver contract, fan-out logic, safety mechanisms (low-confidence, closed markets, wide spreads), cancellation rules, and news field details. It addresses edge cases and provides agents with sufficient context to use the tool effectively without ambiguity.

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

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

Parameter schema coverage is 100%, fulfilling the baseline. The description adds context: for 'depth' it explains quick vs thorough and default; for 'market' it describes three input formats; for 'include_raw' it clarifies behavior and response size impact. This additional information aids correct parameter usage beyond schema details alone.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb 'research' and the resource 'Polymarket bet', effectively distinguishing it from sibling tools like 'polymarket_edges' and 'ask_pipeworx'. The detailed explanation of input types and outputs further clarifies its unique role.

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 scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also describes conditions where the tool may not be appropriate (low-confidence, closed markets, wide spreads) and includes safety notes. While it doesn't directly exclude alternatives, the context and sibling list make the differentiation 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?

Adds substantial detail beyond annotations: explains data pulled per type (revenue, net income, debt for companies; adverse events, approval counts, trials for drugs), sorting by primary metric, and citation URI returns. No contradiction with annotations (readOnlyHint, 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 dense but front-loaded with common query examples. Every sentence provides value, though it could be slightly more structured with line breaks. Still very 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?

Given the complexity (two entity types, multiple data sources, sorting, citation URIs), the description covers all essential aspects. Sibling 'entity_profile' tool exists, and the description correctly positions this tool as a replacement for multiple sequential lookups.

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

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

Schema coverage is 100% but description adds significant meaning: for 'type' clarifies entity-specific data sources, for 'values' gives explicit examples and bounds (2-5), and explains how the results are sorted and returned.

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

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

Description clearly states it performs side-by-side comparison of 2-5 companies or drugs in one parallel call, with specific verbs like 'compare', 'rank', 'head to head'. It distinguishes from sequential single-pack lookups and specifies data sources (SEC EDGAR/XBRL for companies, FAERS for drugs).

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 query patterns ('Compare X and Y', 'X vs Y', 'which is bigger', 'rank these companies') and strongly recommends preferring this tool over sequential lookups. Does not mention when to avoid it, but the guidance is clear and practical.

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

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

Annotations already mark it as read-only, open-world, idempotent, non-destructive. The description adds critical behavioral traits: parallelism, groundedness with verbatim evidence and confidence, explicit gaps[] for unanswered facets, citation format (pipeworx://), and expected latency (15-60s). 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 moderately long but every sentence adds value: core purpose, process, use cases, prerequisites, latency. It is well-structured with front-loaded key insight and logical flow. Minor reduction possible but still efficient.

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

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

Despite no output schema, the description thoroughly explains the return value: structured findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, and gaps[]. This is complete for an agent to understand what to expect and how to synthesize results.

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

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

Schema covers both parameters (100% description coverage). Description adds value: explains depth values numerically (quick=3, standard=5, thorough=8) and clarifies that question should be broad/multi-part, enhancing 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 begins with a strong verb and resource ('Grounded multi-source research in ONE call'), clearly explaining the decomposition and parallel routing to 3,816 tools. It distinguishes from sibling tool ask_pipeworx by contrasting single lookups vs multi-facet 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?

Explicitly states when to use (broad/multi-part questions) and when not (use ask_pipeworx for single lookups). Also covers prerequisites (Pipeworx account, sign-up link) and plan limitations (depth:'thorough' requires paid plan).

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, destructiveHint=false. Description adds that results are 'top-N most relevant' with 'curated examples' and are 'ready to call directly.' This extra context is valuable, though it doesn't detail ranking methodology.

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 a single paragraph but packs all essential information: purpose, domains, output format. It front-loads the core action. Could be slightly more structured (e.g., bullet points) but remains clear and 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 purpose, usage, parameters, and output (names, descriptions, schemas, examples). Missing an explicit output schema, but description compensates by detailing what the response contains. Adequate for a discovery tool.

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

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

Input schema covers 100% of parameters with descriptions. Description goes beyond by noting aliases (task, q, description, search) and default/max limit, giving the agent flexibility in how to specify the query.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and emphasizes that results include full schemas and examples, making it distinct from any sibling tools.

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

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

Explicitly advises using this tool when browsing or discovering tools, and specifically says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use and strategic 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?

Beyond annotations (readOnly, openWorld, idempotent, not destructive), the description adds behavioral details: it fans out across multiple sources, specifies what returns (cik, filings, fundamentals, patents, news, LEI), notes USPTO sunset and soft-fail, and mentions that names are not supported. No contradiction with annotations.

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

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

The description is front-loaded with example queries and is comprehensive but slightly verbose. While every sentence adds value, it could be more concise without losing information. Still, it is 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 there is no output schema, the description fully explains the return structure: includes specific fields, sources, and order. It covers edge cases (unsupported name, USPTO sunset) and dependencies (resolve_entity). Complete for this tool.

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

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

Schema coverage is 100% and the description adds meaning beyond the schema: clarifies that 'value' can be ticker or zero-padded CIK (not name), and 'type' is restricted to 'company'. This helps the agent understand valid inputs.

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

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

The description clearly states the tool's purpose with specific verb 'profile' and resource 'US public company', and includes example queries. It distinguishes itself from chaining multiple single-source lookups, making it clear when to use this tool.

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

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

The description explicitly states when to prefer this tool ('ALWAYS PREFER over chaining...when user asks for holistic view') and when not to use it (if only a name, use resolve_entity first). Provides clear context and alternatives.

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

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

Annotations already provide destructiveHint true and readOnlyHint false. Description adds context about clearing sensitive data, reinforcing but not adding new behavioral info 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?

Three concise sentences with no fluff. Action verb front-loaded. Every sentence adds value.

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

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

Adequate for a simple deletion tool with one parameter and no output schema. Provides when-to-use context. Could mention permanence or key existence requirements but not necessary.

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

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

Schema covers 100% of parameters with description 'Memory key to delete'. Description repeats 'by key' but adds no new meaning. Baseline 3 is appropriate.

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

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

Clearly states verb 'delete' and resource 'memory by key'. Distinguishes from siblings like 'remember' and 'recall'.

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

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

Explicitly lists when to use: stale context, task done, clear sensitive data. Also advises pairing with remember and recall.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds process details (fetches, extracts, emits) consistent with annotations. Could mention potential rate limits or content size constraints.

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

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

Single paragraph, front-loaded with the core action, every sentence adds value, no redundancy.

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

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

For a simple tool with full annotation coverage and two parameters, the description covers purpose, process, and usage. Lacks mention of URL accessibility or output handling, but still fairly 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. Description does not add significant meaning beyond schema for parameters; the 'max_links' default and max are only in schema.

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

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

The description clearly states the tool generates a specific file (llms.txt) for any URL, with explicit use cases. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on file generation rather than scanning.

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

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

Provides three explicit use cases (client sites, own projects, auditing competitors). Lacks explicit when-not-to-use or alternatives, but context from sibling list implies different tools for different tasks.

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, which establish safety. The description adds details on returned metadata (title, authors, PDF URL), exceeding what annotations provide.

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

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

Two sentences, no wasted words. The description is front-loaded with the primary action and immediately provides examples. Every sentence adds useful 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 a single parameter, high schema coverage, and presence of an output schema (not shown but referenced), the description is complete. It covers what the tool does, how to use it, and what to expect in return.

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

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

The schema already has 100% coverage with a description of arxiv_id. The description adds value by providing example IDs and clarifying the return includes full metadata, going beyond the schema alone.

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

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

The description clearly specifies fetching a single arXiv paper by its ID, with concrete examples. It distinguishes from sibling tools like search_papers by focusing on retrieval of a specific resource.

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

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

The description provides examples of valid IDs and mentions the return metadata, which guides usage. While it doesn't explicitly contrast with alternatives, the context of sibling tools makes the use case clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint; description adds return fields. Lacks pagination mention but adequate given 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 front-loaded sentences, no wasted words, efficient and clear.

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

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

Covers return fields and usage; no output schema needed. Minor omissions like ordering or limits but acceptable for a simple list tool.

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

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

Schema coverage is 100% with parameter description; description does not add extra meaning beyond schema, 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?

The description clearly states the tool lists the caller's active subscriptions, specifies return fields, and distinguishes from siblings like subscribe and unsubscribe.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel,' providing clear when-to-use context and implicit 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?

Beyond annotations (all false), description adds rate limit (5 per identifier per day) and free usage policy. 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?

Front-loaded with purpose, then usage guidelines, then behavior notes. Every sentence adds value; no filler.

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 necessary aspects: when to use, what to include, limitations (rate limit, free, no quota). No output schema needed for fire-and-forget feedback.

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 100%, but description adds nuance: explains enum values in context, gives message formatting guidance (1-2 sentences, 2000 chars max), and clarifies optional context fields.

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 verb (tell), resource (Pipeworx team), and scope (broken, missing, needs). It distinguishes from all siblings as 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 lists when to use (bug, feature/data_gap, praise) and what not to do (don't paste end-user prompt). No alternative tools needed.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds significant behavioral context: data source (CF analytics-engine), no PII, caching behavior (5min-1h), and aggregation method. No contradictions.

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

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

The description is concise (three sentences plus bullet list) and front-loaded with the core purpose. Every sentence adds value, with no unnecessary words.

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

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

The tool is simple (one optional parameter, no output schema, safe annotations). The description covers purpose, use cases, data source, privacy, and caching. It gives a clear idea of return values (top tools, packs, volume), making it 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%, and the schema's description already explains the enum values and their implications. The description does not add new parameter-level detail, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns top tools, top packs, and call volume over a recent window, with a specific verb-resource structure. It distinguishes itself from 28 sibling tools by focusing on aggregate usage trends, not individual tool details or other functionalities.

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 concrete use cases (discovering hot data, confirming canonical tool, checking alignment) and explains window behavior. It lacks explicit when-not-to-use or alternative comparisons, but the use cases are clear and actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral context: algorithm details (monotonicity, partition check), failure conditions (no args, placeholder filter), semantic anchoring (Jaccard similarity ≥0.30), fill check (theoretical_edge vs realizable_edge), and response structure. 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 lengthy but well-structured, with early statement of requirements and purpose, followed by clear sections for each mode, semantic anchor, partition filter, response, fill check, and sibling reference. Every sentence adds value, though the length is justified by the tool's complexity. Slightly less concise than ideal but still efficient.

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

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

Given the tool's complexity (two modes, multiple algorithms, fill check) and absence of an output schema, the description comprehensively covers the response structure (opportunities[], partition_check details), trade execution caveats (realizable edge, thin legs), and references a related tool for custom sizing. No critical gaps remain.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant meaning beyond the schema: explains the 'event' mode walks child markets and checks ordering/partition, while 'topic' mode searches related events and flattens markets. Provides real-world examples (slugs, seed questions) and clarifies mutual exclusivity. This greatly enhances an agent's understanding of parameter behavior.

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

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

The description states a specific verb ('Find arbitrage opportunities') and resource ('on Polymarket'), with detailed algorithmic methods ('monotonicity violations + partition-sum checks'). It distinguishes two modes ('event' for single-market, 'topic' for cross-event) and explains what each does, clearly differentiating from sibling tools like polymarket_edges and polymarket_fill_risk.

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 `event` or `topic` and warns that no args fails. Recommends `event` for a specific market and `topic` for cross-event scanning, explaining when cross-event catches patterns single-event misses. Provides a 'do not trade' condition when realizable_edge_pp ≤ 0, and directs to a sibling tool ('polymarket_fill_risk') for custom sizing.

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

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

The description reveals extensive behavioral traits beyond annotations, such as the three model families, edge calculation methodology, caching (1h KV cache), diagnostics structure, and warnings like 'your edge may already be in the price'. 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 well-structured with sections and headers. Every sentence adds necessary detail given the complexity (9 params, 3 model families, caching, diagnostics). Could be slightly more concise, but justified.

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

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

No output schema, so description fully covers return structure: by_segment segments, fed_candidates/fed_note, _diagnostics with funnel counters. Also explains per-opportunity fields. 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% with good descriptions, but the tool description adds significant value: e.g., explaining min_partition_leg_kelly vs min_kelly, default values context, and tradeable-edge filter interactions. A minor gap is no explicit parameter grouping, but overall strong.

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 ('Scan'), resource ('top Polymarket markets'), and unique value proposition ('return opportunities where Pipeworx data disagrees with market price'). It distinguishes from siblings like polymarket_arbitrage and bet_research by specifying its niche.

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 'Built for what should I bet on today' and details tradeable-edge knobs with usage guidance. While it doesn't directly compare to siblings, the context makes it clear when to use this tool.

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

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

Annotations already indicate safe read and idempotent behavior. The description adds significant value by detailing the output structure (tracked, expired, snapshot_dates), decay computation, and limitations (TTL, not intraday). No contradiction with annotations.

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

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

The description is long but efficient, packing purpose, output details, and limits into a coherent block. Front-loaded with the core question. Could be slightly more concise, but no wasted sentences.

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

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

With no output schema, the description explains return values in detail (tracked, expired, snapshot_dates with fields). It covers behavior, limits, and computation. Adequate 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 covers both parameters with descriptions. The description adds defaults, ranges, and explanation of the window parameter's meaning (snapshot family). This provides additional context beyond the schema alone.

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

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

The description clearly states the tool provides edge persistence and decay telemetry, answering a specific question about edge longevity. It is specific about the resource (polymarket_edges snapshots) and the action (tracking decay). However, it does not explicitly differentiate from sibling tool 'polymarket_edges', which likely provides current edge 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 usage when historical edge persistence is needed, but does not explicitly state when not to use this tool or mention alternatives like 'polymarket_edges' for current snapshot data. The context of use is clear but exclusions are 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?

Annotations (readOnlyHint, idempotentHint, destructiveHint) indicate a safe read-only operation. The description adds behavioral specifics: walks the order-book ladder, returns verdicts like clean/degraded/cannot_fill, and discloses risks of forced directional exposure in basket mode, all consistent 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 comprehensive but somewhat verbose. It is well-structured with clear sections for each mode and a usage note, but could be slightly more concise to improve readability.

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

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

Despite lacking an output schema, the description thoroughly lists all return fields for both modes, including verdict, profit_usd, per-leg detail, and thin_legs identifiers. It covers edge cases like forced directional risk, making it complete for an AI agent to understand outputs.

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?

Although schema covers all 4 parameters with descriptions, the tool description adds significant value: it clarifies the dual-mode behavior of side (auto-default for basket), explains size_usd in basket mode as settlement notional shares per leg, and provides default values and ranges beyond the schema.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes and explicitly ties usage to sibling tools like polymarket_arbitrage and polymarket_edges, making differentiation clear.

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 instructions: 'REQUIRES one of market (single-market mode) or event (basket/partition mode).' It details when to use each mode and advises to use this tool before acting on arb signals or trades above ~$500, explaining risks of partial 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 indicate safe, read-only, idempotent behavior. The description adds extensive behavioral context: explains compatibility_warning triggers, temporal alignment, skipped cross-type/subtype counters, and when spreads are meaningless. 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 thorough but well-structured, with clear sections for modes, response, and safety fields. Every sentence adds value, though it could be slightly more concise. Front-loaded with core purpose.

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

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

Given the tool's complexity and lack of output schema, the description covers all essential aspects: purpose, modes, response structure, safety fields, temporal alignment, and limitations. It is comprehensive enough for an agent to understand and use correctly.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds value by explaining the interplay between topic and explicit tickers, listing valid topic values, and noting override behavior. This goes beyond the schema descriptions.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from other tools by its cross-venue focus. The verb 'computes' and resource 'spread' are specific, and it differentiates from siblings like polymarket_arbitrage.

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 describes two usage modes (topic shortcuts vs explicit tickers) and includes detailed guidance on when spreads are meaningful vs when to expect compatibility warnings. It warns that pre-mapped topics often yield warnings, setting proper expectations.

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 read-only, idempotent, non-destructive behavior. The description adds contextual details: it retrieves previously saved values, is scoped to identifier, and pairs with save/delete. No contradictions. It does not mention auth specifics or rate limits, but these are not expected for this simple read operation.

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

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

The description is three sentences, front-loaded with the core action, then provides specific examples, scope, and pairing. Every sentence adds value with no redundancy or fluff.

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

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

For a tool with one optional parameter and no output schema, the description covers retrieval behavior and scope adequately. It lacks mention of error cases (e.g., key not found) or return format, but the simplicity of the tool makes this minor. Overall complete enough for an agent to use correctly.

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

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

Schema coverage is 100% and already describes the 'key' parameter as optional with 'omit to list all keys'. The tool description repeats this explanation with examples. No additional constraints, formats, or edge cases are added 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 retrieves a value by key or lists all keys if omitted. It provides concrete examples (ticker, address, notes) and explicitly distinguishes it from sibling tools remember and forget. The verb 'retrieve' and 'list' are specific and action-oriented.

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

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

The description explains when to use: to look up stored context without re-deriving. It mentions the scope (by identifier) and pairs with remember/forget. While it lacks explicit when-not-to-use, the paired tools imply appropriate alternatives. No explicit exclusion is given, 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?

Beyond annotations (readOnly, idempotent, destructive false), it explains that returned events include specific fields, mark_read affects future calls, and polling works fine. 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?

Concise paragraph, front-loaded with purpose and key details. Every sentence adds value: purpose, fields, filtering, alternative access. 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?

Given 5 optional parameters and no output schema, the description is complete: explains return fields, filtering options, side effects of mark_read, and alternative access method. An agent can confidently invoke this 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 covers 100% of parameters with descriptions. Description adds value by providing examples (e.g., 'sec_8k' for type), clarifying that since is ISO timestamp and mark_read sets read flag for subsequent calls, enhancing usability 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 'Pull fired events from your subscription feed' and specifies it returns recent alerts with source, citation_uri, and raw payload. It distinguishes itself from sibling tools by focusing on alert retrieval, not subscriptions or other operations.

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

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

Provides context on filtering by type and since, setting mark_read for polling, and mentions an alternative GET endpoint. Lacks explicit when-not-to-use or direct sibling comparisons, but gives sufficient usage guidance.

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

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

The description discloses behavioral traits beyond annotations: fan-out to multiple sources (SEC EDGAR, GDELT/GNews, USPTO), fallback mechanism, soft-fail for USPTO due to API sunset, and the fact that the tool is read-only and idempotent (consistent with 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?

The description is lengthy but front-loaded with example queries and well-structured. Every sentence provides value, but some details (e.g., GDELT vs GNews distinction) could be slightly trimmed. Still, 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 no output schema, the description fully compensates by detailing the output structure (changes[] grouped by source, total_changes, citation URIs). It explains all sources, fallbacks, and parameter behavior. The contextual completeness is high.

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

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

Schema coverage is 100%, but the description adds meaningful extra guidance: for `since` it recommends typical values and explains relative vs ISO date, for `value` it gives examples (ticker or CIK), and for `type` it notes only 'company' is supported. This adds practical 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's purpose: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It specifies the output format (structured changes[], total_changes, citation URIs) and distinguishes from sibling tool entity_profile.

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

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

The description provides explicit guidance on when to use (queries like 'What's new with X', 'latest on Y') and when to avoid ('Use entity_profile instead when you want the static profile'). It also explains fallback behavior (GDELT→GNews) and parameter recommendations ('Use "30d" or "1m" for typical monitoring').

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 idempotentHint=true and destructiveHint=false. The description adds valuable context: key-value pairs are scoped by identifier, authenticated users get persistent memory, and anonymous sessions retain memory for 24 hours. This goes beyond annotations and helps the agent understand data lifecycle.

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 five sentences with no redundant words. Purpose is front-loaded, followed by usage guidance and behavioral traits. Every sentence adds value, making it easy to parse quickly.

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

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

Given the tool's simplicity (2 required params, no output schema, no nested objects), the description fully covers what the agent needs: what to store, when to use, persistence behavior, and how it relates to siblings. No gaps remain.

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

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

Schema coverage is 100% with descriptions for both key and value. The description adds example patterns (e.g., 'subject_property') but does not significantly enhance understanding beyond the schema. Baseline 3 is appropriate as the schema suffices.

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 stores key-value pairs for later reuse, with concrete examples like 'a resolved ticker, a target address, a user preference'. It distinguishes itself from sibling tools 'recall' and 'forget' by mentioning them as partners, making its unique purpose clear.

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

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

The description says 'Use when you discover something worth carrying forward... so you don't have to look it up again.' This provides clear guidance on when to invoke. It also mentions pairing with recall and forget, indicating alternatives, though it does not explicitly state when not to use.

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

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

Annotations already declare read-only, idempotent, open world. Description adds that it cascades through multiple endpoints internally, and details return fields (ticker, CIK, RxCUI, etc.) and input acceptance (ticker, CIK, name; brand, generic).

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?

Concise yet packed with information. Starts with common queries, then core purpose, then detailed type breakdowns. No redundant sentences; each sentence adds value.

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

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

Covers both supported types, input variants, and return fields. Minor omission: does not explicitly state output format (e.g., JSON) but implicitly clear from examples. With no output schema, description serves its purpose well.

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

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

Schema coverage is 100% with descriptions, but the description adds significant value: explains auto-disambiguation for company, what each type returns, example values (AAPL, ozempic). Elevates 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 resolves names to canonical identifiers, with specific examples and supported types. It distinguishes from sibling tools like 'entity_profile' and 'compare_entities' by focusing on ID lookup.

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

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

Explicit instructions: 'Use FIRST whenever you have a name but need an ID.' Examples cover typical queries. It implies when not to use (if ID already known) and states it replaces multiple manual lookups.

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

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

Description adds details beyond annotations: it mentions probing each entity with ai_visibility_check, ranking by score, and returning score, confidence, signal density per entity. Annotations already mark it as readOnly, idempotent, not destructive, and open world. No contradiction.

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

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

Description is a single concise paragraph with front-loaded purpose. It could be slightly more structured (e.g., separating input/output details), but it's effective with minimal waste.

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

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

Given 4 parameters, no output schema, the description adequately explains the return format (ranked list with score, confidence, signal density) and how inputs are used. It is complete enough for agent invocation.

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

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

Schema coverage is 100%, but description adds context: first entity is treated as subject, models default to workers-ai, _apiKey needed only if anthropic is in models, context disambiguates. This adds meaning beyond the schema descriptions.

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

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

Description clearly states it compares AI visibility across multiple entities by probing each with ai_visibility_check and ranking results. It differentiates from sibling tools like ai_visibility_check (single entity) and compare_entities (generic 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?

Description provides explicit use case: competitive AI-marketing audits, with an example question. It implies when to use (multi-entity comparison), but does not explicitly state when not to use it or exclude alternatives.

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

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

The description adds significant behavioral context beyond annotations, such as 'Partial failures degrade gracefully — bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out'. This discloses timing and error-handling behavior not hinted at by annotations alone.

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

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

The description is front-loaded with the core purpose and provides structured details in subsequent sentences. While verbose, each sentence adds value (usage guidance, return format, limitations). Minor redundancy could be trimmed, but overall 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 tool's complexity (two external sources, partial failures, return structure) and no output schema, the description fully covers what is returned (summary block, advisories, links, alternative versions), explains fallback and timing, and is complete for agent decision-making.

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 described. The description adds minor nuance (e.g., 'Scoped packages (e.g. '@types/node') are accepted', version defaults to latest), but does not substantially expand beyond schema content. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose as a composite check for adding npm packages, specifying the verb 'scan' and the resource 'npm package'. It distinguishes itself from sibling tools by explicitly describing its unique multi-source fan-out across deps.dev and bundlephobia, which no sibling tool does.

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

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

The description provides explicit guidance on when to use this tool (e.g., 'is X safe / popular / small', 'what does adding lodash cost me') and when not to ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This clearly advises the agent on appropriate contexts.

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

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

Annotations already provide idempotentHint, readOnlyHint, etc. The description adds the return fields (id, title, authors...), which is useful but not extensive. 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, no waste. Front-loaded with primary purpose, then details on query syntax and return format. Each sentence adds necessary 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 output schema existence, description covers key behaviors and return values. Could mention pagination or result limits, but max_results parameter addresses this. Complete for typical use.

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

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

Schema coverage is 100%, baseline 3. Description adds value by explaining query prefixes and combination syntax beyond the schema's description, with concrete examples that clarify parameter usage.

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 'Search arXiv preprints' with immediate clarity on the resource and action. It distinguishes from siblings like 'get_paper' by specifying search functionality, and the query syntax explanation reinforces its purpose.

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

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

Provides explicit examples of query prefixes (au:, ti:, etc.) and boolean operators (AND/OR/ANDNOT), giving clear context on usage. However, no direct comparison to sibling tools like 'get_paper' for when to use this over alternatives.

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

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

Annotations already declare read-only and non-destructive. Description adds how it works: embeddings, windowing, character offsets, similarity scores, truncation at 200K chars with flag. No contradictions.

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

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

Four sentences, front-loaded with purpose and usage. Every sentence adds value: use case, mechanism, pairing with sibling, technical details. 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 complexity, no output schema but description covers return format (passages with offsets and scores), size limits, and pairing with a sibling. Complete for an agent to understand and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by providing examples for query parameter and clarifying the text parameter's origin ('fetched record'). Also explains the algorithm and output nature, though that's more behavioral. Still, adds meaningful context.

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 does semantic search inside a previously fetched record, with specific examples (SEC 10-K, article). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and contrasting with whole-document approaches.

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: 'when the record is too big to cram into the prompt'. Mentions alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' Provides clear context and 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 only provide readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: account requirements, type-specific parameter explanations, delivery channel details with constraints (SMS cap, webhook auto-disable), and returns the new subscription ID. 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 well-structured: it begins with the main purpose, then requirements, type examples, and delivery options. Every sentence adds unique information without redundancy, making it efficient and front-loaded.

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

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

Given the complexity (3 parameters, nested objects, no output schema), the description covers the tool's purpose, prerequisites, type-specific params, delivery channels with constraints, and return behavior (subscription ID). No gaps are evident.

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 parameter descriptions. The description adds value beyond schema by providing examples, format details (e.g., E.164 phone number), and required vs optional conditions (e.g., 'sponsor or condition required'). Baseline 3 due to high coverage, but additional context warrants a 4.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' and specifies it returns a subscription ID. It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation, with no ambiguity.

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

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

It explicitly requires a Pipeworx OAuth account, lists supported types and delivery channels, and mentions constraints like SMS 10/day cap. However, it does not provide explicit guidance on when to use this tool versus alternatives (e.g., list_subscriptions, unsubscribe) 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, openWorldHint, idempotentHint, destructiveHint. The description adds value by detailing the returned content structure (category buckets, example questions, tool+argument shapes) and that it uses the live catalog. No side effects disclosed, but none expected given 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?

Well-structured, front-loads purpose, and uses bullet-like lists for topics and examples. Slightly verbose but every sentence adds value. Appropriate length for the richness of the tool.

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

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

Given the simple single-optional-param structure and no output schema, the description fully covers what the tool does, when to use it, and what result to expect. No gaps.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning by enumerating possible topic values ('finance', 'pharma', etc.) and explaining that omission yields full spread. This goes beyond the schema's description.

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

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

The description uses specific verbs and clearly states the tool returns category-bucketed example questions with exact tool+argument shapes. It distinguishes itself from siblings by explicitly positioning it as the onboarding entry point.

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

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

Explicitly states when to use: 'when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also explains the optional topic parameter and what happens when omitted.

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=false, destructiveHint=false, idempotentHint=true), the description adds critical behavioral details: ownership enforcement, deactivation (not deletion), and that historical events remain via recent_alerts. 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 extraneous words. Core action is front-loaded. Every sentence adds value: action, constraint, and consequence. Ideal conciseness.

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

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

For a simple tool with one parameter and no output schema, the description covers the main behavioral aspects: ownership, deactivation, and historical impact. It could mention error cases (e.g., invalid id), but overall it is 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 single parameter 'id' is fully described in the schema as 'Subscription id (uuid) returned by subscribe.' with 100% coverage. The description adds meaning by specifying ownership context, which is not in the schema. This exceeds 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 'Cancel a subscription by id.', providing a specific verb and resource. It further distinguishes from siblings like 'subscribe' and 'list_subscriptions' by explaining ownership enforcement and that the row is deactivated, not deleted.

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 'Ownership is enforced — you can only cancel your own subscriptions.', which is a key usage constraint. It doesn't explicitly state when not to use this tool, but the context is clear that it is for personal subscriptions only.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds valuable behavioral context: return format (verdict types, citation, percent delta) and efficiency gains (replaces 4-6 calls). No contradictions.

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

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

The description is front-loaded with natural language triggers and clearly structured. Although slightly verbose, every sentence adds value. Could be more concise but still effective.

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

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

Given the tool has one parameter, no output schema, and comprehensive annotations, the description fully covers purpose, usage, behavior, and returns. No gaps identified.

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?

Single parameter 'claim' has 100% schema description coverage. The tool description adds context with examples and scope (company-financial claims), enhancing the schema's meaning. Score above baseline due to added semantic value.

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

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

The description clearly defines the tool as a natural-language claim verification tool against authoritative sources. It starts with example queries, making its purpose immediately understandable, and distinguishes it from siblings by noting it replaces multiple sequential calls.

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: 'whenever the agent needs to check whether something a user said is factually correct.' Also provides scope limitations (v1 supports company-financial claims), guiding appropriate use.

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