Packagephobia

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

Annotations already declare idempotent, read-only, non-destructive behavior. The description adds critical behavioral details: free default model vs. BYO Anthropic key with direct payment, payment model, and return structure (per-model + combined). 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?

Three sentences with no fluff. The first sentence states core purpose and output format. Each subsequent sentence adds necessary detail (model options, return shape, and use cases). Ideal front-loading.

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?

Without an output schema, the description explains return structure (score, confidence, signals, raw_response) and scale (0-100). It covers all 4 parameters. Lacks examples, error handling, or deeper score semantics, but sufficient for an agent to understand inputs and 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?

Schema description covers all 4 parameters (100%). The description adds meaningful context: explains '_apiKey' is optional and passed through, clarifies 'models' values ('workers-ai', 'anthropic'), and notes 'context' disambiguates. Default model and return format are also specified, going well 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 probes LLMs for entity visibility and scores it (0-100). It specifies the resource (LLMs), action (probe), and outputs (per-model score). It also distinguishes from siblings like 'scan_competitor_ai_presence' by targeting general brand/product/topic visibility audits.

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 use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) but does not directly contrast with siblings or state when not to use. The context signals and sibling list imply differentiation, but description lacks explicit 'when not to use' guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent. Description adds that it routes to 4,789 tools across 1,249 sources, fills arguments, and returns structured answers with pipeworx:// citations. This provides useful context beyond annotations, though the exact return structure is not detailed.

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 somewhat lengthy but well-structured. Key guidance is front-loaded in bold ('PREFER OVER WEB SEARCH'). Every sentence adds value, including examples and sibling differentiation. Could be slightly more concise but highly 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's complexity as a meta-router, the description covers purpose, usage scope, behavioral details (routing, citations), and tier compatibility. It does not describe the output structure (no output schema), but the examples and citation mention suffice for completeness.

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

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

Schema coverage is 100%, fully documenting the single required parameter 'question' and its aliases (q, text, input, query, prompt). The description does not need to add more; baseline 3 applies.

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 routes factual questions to a vast set of verified sources, prioritizing over web search. It uses a specific verb ('ask') and resource ('Pipeworx') and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly tells when to use this tool ('PREFER OVER WEB SEARCH', 'START HERE for most questions'), when to step up to alternatives (ask_pipeworx_grounded for verbatim evidence, deep_research for broad multi-part questions), and provides numerous examples of appropriate queries.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description details the refusal mechanism with specific reasons (not_in_source, no_tool_match, etc.) and the return structure. It also discloses the extra LLM call cost, adding significant behavioral context.

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

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

The description is moderately concise with about 6 sentences, each providing essential information. It is front-loaded with the key differentiator ('Hallucination-resistant answer mode') and structured logically. Slight reduction in length could improve conciseness, but it remains 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 structure (answer, evidence, confidence, source, fetched_at, refusal_reason) and the possible refusal outcomes. Given the tool's complexity (routing through 4,789 tools), this covers all necessary 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?

Schema coverage is 100% with descriptions for each parameter, but the description adds value by explaining aliases (q, text, input, etc.) and clarifying that the question is in natural language. This enhances usability 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 is a 'hallucination-resistant answer mode for high-stakes reads' and explains its unique process of extracting answers solely from tool results. It effectively distinguishes itself from the sibling tool 'ask_pipeworx' by emphasizing its grounded nature and specific use cases.

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 ('whenever an answer will be quoted, cited, or acted on') and when-not-to-use ('prefer ask_pipeworx for casual lookups'), along with high-stakes examples like financial verdicts and medical lookups. It also notes the extra LLM call cost as a tradeoff.

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

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

The description goes well beyond annotations (readOnlyHint, idempotentHint) by detailing safety mechanisms (low-confidence resolution short-circuits), data collection behavior (fan-out to external APIs), response structure, and edge cases like closed/dead markets and wide spreads. Annotations already declare the tool safe, and the description enriches with actionable behavioral details.

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

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

The description is long but information-dense. It uses bolded section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) for structure. However, it could be more concise by grouping related concepts, e.g., combining coverage of low-confidence and closed markets into one safety paragraph. Still, every sentence serves a 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 (multiple classifiers, fan-out to various data sources, rich response structure), the description covers all necessary aspects: input types, classification, evidence sources, response fields, safety checks, edge cases (low confidence, closed markets, wide spreads, cancellation rules). No output schema exists, so the description must explain return values, and it does so thoroughly.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by explaining market input flexibility (slug, URL, question text) and the meaning of include_raw (keeping responses small vs full payloads). Depth is already well-documented in the schema. The description enhances understanding 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 uses a specific verb ('Research') and resource ('Polymarket bet') and clearly distinguishes the tool's comprehensive evidence-gathering role from sibling tools like 'polymarket_edge_tracker' which focus on edge detection. It states 'Pulls relevant Pipeworx data' and enumerates classifiers and fan-out examples, leaving no ambiguity about 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?

The description explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains when the tool short-circuits (low-confidence matches, closed markets). However, it does not explicitly mention when not to use it or compare to alternatives like 'polymarket_arbitrage' or 'polymarket_edges', which keeps it from a perfect score.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description goes beyond by detailing sorting by primary metric (so 'largest' reads off the top), handling off-calendar fiscal years correctly, and noting that it replaces 8–15 sequential lookups. These additions provide rich behavioral context without contradicting annotations.

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

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

The description is somewhat lengthy but well-structured. It opens with user intents, states the core function, then details each entity type, sorting behavior, and efficiency. Every sentence adds value, and the structure is logical. It could be slightly trimmed, but it's clear 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 tool's complexity (multiple entity types, data sources, sorting), the description covers key aspects: supported types, data retrieved, sorting, and return includes citation URIs. It lacks explicit detail on the exact structure of the paired data (e.g., which metrics are returned for each type), but the description still provides sufficient context for correct usage. No output schema exists, so this level of detail is reasonable.

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 significant meaning: for 'type', it explains the distinction between company and drug; for 'values', it provides examples (tickers for company, drug names) and constraints (2–5 items). It also explains what data each type pulls and how results are sorted, which is not in the schema. This enriches parameter understanding far beyond the schema alone.

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

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

The description starts with common user queries ('Compare X and Y', 'X vs Y') and clearly states it performs side-by-side comparison of 2–5 companies or drugs in a single call. It distinguishes itself from sequential lookups and specifies what data each entity type retrieves (financials from SEC for companies, adverse events and trial counts for drugs). This makes the purpose immediately understandable and distinct.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing a clear directive for when to use this tool. It also describes the supported entity types and the data returned, but does not explicitly mention when not to use it or name alternatives beyond the implicit sequential lookups. This is strong guidance but lacks explicit exclusions.

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 account requirement, paid tier for 'thorough', expected response time (15-60s), and that it returns empty gaps[] for topics not in catalog. Annotations already provide readOnlyHint etc., but description adds significant behavioral context.

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

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

Well-structured with critical info front-loaded (account requirement, alternative tool). While lengthy, each sentence adds value and the structure is 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?

Given no output schema, description compensates by describing output format (findings packet with verbatim evidence, confidence, source, citation, gaps[]). Covers prerequisites, behavior, and edge cases comprehensively.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining depth levels (quick=3, standard=5, thorough=8 facets) and that question can be 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?

Description clearly states it performs grounded multi-source research across 1249 structured data sources, distinguishes from sibling tools like ask_pipeworx and is explicitly not open-web search.

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 over structured data) and when not (breaking news, single lookup), with clear alternatives like ask_pipeworx.

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, idempotentHint, destructiveHint. The description adds that results include 'names, descriptions, and full input schemas (with curated examples)' and are 'ready to call directly, no second schema lookup needed', providing valuable behavioral context beyond annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and every sentence adds value without verbosity.

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

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

Despite no output schema, the description fully explains the return value (tool names, descriptions, schemas) and lists domains. Given the tool's discovery purpose and rich annotations/schema, 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 description coverage is 100%, so baseline is 3. The description provides example queries but does not add parameter-specific meaning beyond what the schema already documents.

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 'Find tools by describing the data or task', clearly stating the verb and resource. It lists numerous domains (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools which are domain-specific.

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', providing clear when-to-use guidance. It implies this is for discovery before using specific tools, though it doesn't list explicit 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, openWorldHint, idempotentHint, destructiveHint) indicate safe, idempotent read-only behavior. The description adds details beyond annotations: fans out across multiple sources, notes USPTO patent sunset and soft-fail, describes fallback from GDELT→GNews, and mentions parallel execution. 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 example queries and purpose, then lists return data. While slightly verbose due to detailed return fields, every sentence contributes useful information. It is well-structured for an AI agent.

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

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

Given the tool's complexity (multiple sources, fallbacks, sunset) and lack of output schema, the description adequately explains what is returned (specific fields). It covers constraints and behavior, making it reasonably complete for use without additional 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 clear descriptions. The description reinforces parameter semantics by providing examples ('AAPL', '0000320193') and explaining that names are not supported. This adds value beyond the schema's descriptions.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company'. It lists specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and return fields, distinguishing it from siblings like 'compare_entities' and 'deep_research' by emphasizing it is preferred over chaining single-source 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?

The description explicitly says 'ALWAYS PREFER over chaining single-pack... lookups when the user asks for a holistic view' and instructs to use 'resolve_entity first if you only have a name'. It also clarifies that only 'company' type is supported. No explicit exclusions, but clear context for when 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 provide destructiveHint=true and idempotentHint=true. The description adds minor context about 'previously stored' and 'sensitive data' but does not disclose additional behavioral traits like error handling or persistence semantics.

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 concise, front-loaded sentences with zero waste. Every sentence serves a 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 a single parameter with full schema coverage, annotations, and no output schema, the description is complete. It covers usage, context, and sibling relationships.

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

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

Schema coverage is 100%, so the schema already documents the 'key' parameter fully. The description does not add any additional meaning beyond what the 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 'Delete a previously stored memory by key', which is a specific verb+resource combination. It distinguishes itself from sibling tools 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?

The description explicitly lists use cases: 'when context is stale, the task is done, or you want to clear sensitive data' and suggests pairing with 'remember' and 'recall', providing clear guidance on when to use this tool versus 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 read-only, idempotent, and non-destructive behavior. The description adds valuable context: it fetches the page, extracts title/description/key links, and emits markdown, which goes beyond the annotations without contradiction.

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

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

The description is concise (3 sentences plus one bullet-like list of use cases), front-loaded with the main action, and every sentence adds value. No superfluous 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 lacking an output schema, the description explains the output format and intended usage. With annotations covering safety and parameters fully described, the description is complete for 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?

Both parameters are fully described in the schema (100% coverage). The description does not add additional semantics beyond what the schema provides, so a 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 generates an llms.txt file for a given URL, specifying the output format and use cases. It uses a specific verb-resource combination and distinguishes itself from sibling tools by focusing on generating the standard llms.txt file.

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 (client site indexing, personal project drafting, competitor auditing) which guide when to use the tool. However, it does not explicitly mention when not to use it or directly compare to alternatives like scan_competitor_ai_presence.

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, non-destructive. Description adds useful context: returns specific fields and usage intent. No contradictions.

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

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

Two sentences: first states purpose and return fields, second provides usage guidance. No wasted words, front-loaded with key information.

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

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

For a simple list tool with one optional parameter, description covers purpose, return fields, and usage. Lacks mention of pagination or sorting, but not critical given annotations and schema.

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

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

Schema coverage is 100% with a description for include_inactive. Description does not reiterate or expand on parameter meaning beyond the schema, which is acceptable but adds no extra 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?

Clearly states it lists the caller's active subscriptions and enumerates returned fields (id, type, params, etc.). Differentiates from sibling tools subscribe and unsubscribe by focusing on listing existing subscriptions.

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 cases: reviewing before adding more subscriptions or finding an id to cancel. Does not explicitly state when not to use, 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 are all false, but the description adds critical behavioral context: rate-limited to 5 per identifier per day, free with no quota hit, and implies side effects (data sent to team). 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?

Four sentences with efficient structure: purpose, usage scenarios, content guidelines, and constraints. No redundant information, every sentence earns its place.

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

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

Given no output schema and simple feedback purpose, the description is self-contained. Rate limits and quotas are covered, and the content guidelines are clear. No missing elements.

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

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

Schema description coverage is 100% with detailed parameter descriptions. The tool description adds extra context for the 'type' parameter by explaining each enum value's usage, which enriches 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: sending feedback (bug, feature, data_gap, praise) to the Pipeworx team. It distinguishes from siblings by being the only feedback tool among many research and utility 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 describes when to use each feedback type: bug for wrong data, feature/data_gap for missing tools/data, praise for positive experiences. Also provides what to include (tool-specific details, no user prompts) and constraints (rate limit of 5/day, free).

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. The description adds meaningful behavioral context: data is derived from CF analytics-engine, contains no PII, is cached 5min-1h. 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 exceptionally concise: four sentences, front-loaded with purpose, then use cases, then technical details. Every sentence adds value, no wasted words.

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

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

Given the low complexity (1 optional param, no output schema, rich annotations), the description is fully complete. It explains what is returned, data source, privacy, caching, and usage scenarios. 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 has 100% coverage with a single parameter 'window' fully described. The description adds semantic value by explaining that shorter windows surface hot trends and longer windows show steady-state demand, enriching the agent's understanding beyond the enum values.

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

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

The description clearly states the tool returns trending top tools, packs, and call volume over a selected window. It uses specific verbs and resources, and distinguishes itself from siblings like ask_pipeworx and discover_tools by focusing on aggregate usage data from other AI agents.

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 sources, confirming canonical tool, aligning use case) and explains window selection trade-offs. However, it does not provide explicit when-not-to-use advice or list alternative tools for different needs.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses detailed behavioral traits: internal algorithms (monotonicity, partition sum, Jaccard similarity), filters (placeholder slugs, low similarity), and the fill check that validates tradable edge. It also explains output structure and edge cases.

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 a concise summary and then expands into details. While somewhat lengthy, every sentence provides meaningful information (e.g., semantic anchor, partition filter). It is well-organized by mode and internal checks, avoiding unnecessary repetition.

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

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

Despite no output schema, the description covers key output fields (opportunities, gap_pp, suggested_trade, partition_check) and explains the fill check. It addresses important edge cases (placeholder filtering, low similarity rejection) and references a sibling tool for custom sizing. Some details like exact output types are omitted, but overall it is sufficiently complete for an AI agent to understand usage.

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

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

With 100% schema coverage, the baseline is 3. The description adds significant value by explaining each mode's semantics: event mode accepts slugs or URLs for a specific market, topic mode accepts seed questions for cross-event scanning. It also clarifies the no-argument default behavior, 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's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the resource (Polymarket), action (find arbitrage), and method (monotonicity and partition checks). This differentiates it from sibling tools like polymarket_fill_risk or polymarket_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?

The description provides explicit guidance on when to use each mode: no args for trending_scan, event for a specific market (recommended), and topic for cross-event scans. It explains the internal fill check to avoid false positives and directs users to polymarket_fill_risk for custom sizing, addressing when not to use the tool directly.

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 extensive behavioral details beyond annotations: caching (1h at KV level keyed on all knobs), diagnostic fields explaining why segments are empty, and tradeable-edge knobs. It aligns with readOnlyHint and idempotentHint, and no contradiction is present.

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

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

The description is well-structured with clear sections (model families, edge details, knobs, response), but it is lengthy with technical depth. Some details could be condensed without losing clarity, but the front-loading of purpose and usage is 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's complexity (9 parameters, no output schema), the description is very complete. It explains output structure, edge attributes, caching, diagnostics, and edge cases (e.g., Fed bets excluded from ranking, longshot rare-by-design). No gaps remain.

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

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

With 100% schema coverage, baseline is 3, but the description adds substantial value beyond schema: it explains how parameters interact (e.g., min_kelly vs min_partition_leg_kelly), provides tuning advice (e.g., slippage_pp for thin partitions), and clarifies default behaviors.

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 scans Polymarket markets for discrepancies with Pipeworx data, serving the specific use case of 'what should I bet on today'. It distinguishes this from similar sibling tools like polymarket_arbitrage by focusing on Pipeworx disagreement and automatic discovery without paging.

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 for when to use this tool (discovering opportunities where Pipeworx data disagrees) and explains the three segments (model_driven, structural_arbitrage, concentrated_longshot) that help the agent decide. However, it lacks explicit 'when not to use' or direct comparison to sibling tools like polymarket_arbitrage or polymarket_fill_risk.

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

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

Adds significant behavioral details beyond annotations, such as expiration of edges, decay computation from daily closes, snapshot date gaps, and history limits. No contradiction with annotations.

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

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

Description is well-structured with purpose first, then parameter details, then return format. Slightly verbose but 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?

Given no output schema, description comprehensively covers return values (tracked, expired, snapshot_dates) and context (TTL, decay method). Adequate for agent selection.

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

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

Schema coverage is 100% and description largely repeats schema info for parameters (days, window). No additional semantic value beyond defaults and ranges already provided.

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' answering a specific question about edge duration and status. It distinguishes from sibling tools like polymarket_edges by focusing on historical 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?

Provides context on when to use (e.g., 'a fresh wide edge and a 3-week-old wide edge are different trades') and includes limits like 60-day TTL. However, it doesn't explicitly state when not to use or mention alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds detailed behavioral context: walks the ladder, returns fill quality metrics, and warns about partial basket fills converting arb into unhedged positions. 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 relatively long but well-structured with clear sections for single-market and basket modes. It front-loads the core purpose and uses capitalization for emphasis. Every sentence serves a purpose, though slight trimming could improve 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?

Despite no output schema, the description fully explains all return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), verdict system, per-leg details, and risks of thin books and directional exposure. Comprehensive for a 4-parameter tool.

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

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

Schema coverage is 100%, but the description significantly enhances meaning: explains size_usd interpretation per mode, side defaults in basket mode, and the role of market vs event parameters. Adds crucial 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 it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It is specific and differentiates from sibling tools like polymarket_arbitrage and polymarket_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 says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains when not to use it (theoretical overround on thin books not capturable, partial fills cause directional risk). Provides clear context.

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

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

Annotations already mark the tool as read-only and idempotent. The description goes well beyond by explaining compatibility warnings, temporal alignment, skipped leg-pair comparisons, and the conditions under which spreads are meaningless. This provides comprehensive behavioral transparency.

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

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

The description is thorough but somewhat verbose, containing multiple sections and detailed explanations that could be condensed. It follows a logical structure (intro, modes, response, safety fields) but includes some redundancy (e.g., repeated warnings about pre-mapped topics).

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 the absence of an output schema, the description is remarkably complete. It covers input modes, output structure (leg-by-leg prices, top spreads), safety fields (compatibility warnings, temporal alignment), and potential error conditions. No essential behavioral detail is omitted.

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

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

The input schema covers all three parameters (100% coverage). The description adds value by explaining how topic shortcuts auto-map events, how explicit parameters override, and provides example values. This clarifies usage beyond the schema's 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 the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It uses a specific verb ('spread') and resource ('cross-venue'), and it distinguishes itself from sibling tools like polymarket_arbitrage by focusing on two different prediction market venues.

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 details two usage modes (topic shortcuts and explicit tickers) and provides guidance on when each is appropriate. It also warns that pre-mapped topics often return compatibility warnings, setting user expectations. However, it does not explicitly mention when to avoid this tool in favor of alternatives like polymarket_arbitrage.

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. The description adds valuable behavioral context about scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID), going beyond annotations. 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?

Two concise sentences that front-load the core purpose, then add usage guidance and scoping. Every sentence is informative with 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 read-only tool with one optional parameter, the description is complete: explains what it returns, how scope works, and pairs with other tools. No gaps given annotations and schema coverage.

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 property description. Tool description adds context that omitting the key lists all keys, and explains the purpose of the parameter in the broader workflow (retrieve vs list). 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?

Clearly states the tool retrieves a saved value by key or lists all keys when omitted. Explicitly distinguishes from siblings remember (save) and forget (delete), and explains the use case of looking up previously stored context.

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 when to use the tool ('Use to look up context the agent stored earlier... without re-deriving it from scratch'). Mentions paired tools remember and forget, providing clear alternatives and exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: explains what each returned event contains (source, citation_uri, raw payload), and describes the mark_read parameter's side effect of flagging events as read for subsequent calls. 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 compact (~80 words) with each sentence serving a clear purpose: stating the function, listing return fields, explaining filtering, describing side effects, and mentioning an alternative access method. No redundancy or 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?

Given the complexity (5 optional parameters, no output schema), the description adequately covers what the tool returns (source, citation_uri, raw payload) and how each parameter works. It also addresses polling and fallback to the API endpoint. Slightly more detail on pagination or defaults (e.g., default limit=50) would push it to 5.

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 schema descriptions (100% coverage), so the baseline is 3. The description adds valuable context beyond the schema: it gives an example type ('sec_8k'), explains that 'since' is an ISO timestamp, and describes the effect of mark_read. This enriches the parameter understanding.

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

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

The description uses a specific verb ('Pull') and resource ('fired events from your subscription feed'), clearly distinguishing it from sibling tools like list_subscriptions (which lists subscriptions) or recent_changes (tracking changes). It specifies the exact resource and action.

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?

Clearly states that polling works and that the same feed is available via a direct GET endpoint for scripts/dashboards, providing guidance on when to use the tool vs. the API. However, it does not explicitly exclude other tools or scenarios, leaving some ambiguity about sibling 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?

Rich behavioral disclosure: fans out to multiple sources (SEC EDGAR, GDELT, GNews fallback, USPTO), notes PatentsView sunset, describes output format (changes grouped by source, total_changes, citation URIs). No contradiction with annotations.

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

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

Single dense paragraph is efficient but could benefit from slight structuring (e.g., bullet points). No redundant 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 complex tool with multiple data sources, fallback logic, no output schema, the description covers all essential aspects: sources, fallback behavior, date format, output structure, and sibling reference.

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 3 parameters described in schema (100% coverage). Description adds value: explains since accepts ISO date or relative shorthand with examples, suggests '30d' for monitoring, and clarifies type only supports 'company'.

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 defines tool as a change feed for a company, giving specific examples ('What's new with X', 'latest on Y') and distinguishing from sibling 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?

Explicit usage examples provided, and explicit alternative given: 'Use entity_profile instead when you want the static profile'. Clear when to use and when not.

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 key-value storage, scoping by identifier, persistence details (authenticated vs anonymous), and idempotent behavior 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?

Front-loaded with purpose, but slightly verbose with examples and pairing info. Could be tightened without losing clarity.

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

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

Complete for a simple key-value store with full schema and annotations. No missing information about return values (output schema not needed for storage).

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; description adds real-world examples for key (e.g., 'subject_property') and value (any text), adding contextual meaning beyond the schema's generic 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 saves data for reuse, provides specific examples (ticker, address, preference), and distinguishes from siblings (recall, 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?

Explicitly tells when to use: 'when you discover something worth carrying forward' and mentions pairing with recall and forget for complete workflow.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds valuable behavioral context: cascades through multiple internal lookups, replaces 2-3 manual steps, and returns citation URIs. No contradiction with annotations.

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

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

Description is well-structured with front-loaded examples, then use case, then type details. Every sentence adds value, though slightly lengthy. Still concise for the complexity.

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

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

No output schema, but description covers return content for both entity types including citation URIs. With 2 clear params and thorough annotations, the description provides complete context for an 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%, baseline 3. Description adds significant meaning: explains return values per type (ticker+CIK+name+URI for company; RxCUI+ingredient+brand+URI for drug), and acceptable input formats (ticker, CIK, name for company; brand or generic for drug). This fully compensates and provides more than schema alone.

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

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

The description clearly states the tool resolves a user-spoken name to a canonical/official identifier, with specific examples (ticker, CIK, RxCUI) and entity types (company, drug). The purpose is distinct from siblings like compare_entities or 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?

Explicitly advises 'Use FIRST whenever you have a name but need an ID', providing strong usage context. Does not mention when not to use it or alternatives, but the guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: it probes each entity with ai_visibility_check, ranks by score, and surfaces which is most/least recognized. It also details the return content (score, confidence, signal density). 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?

Two sentences with no wasted words. The first sentence states the core purpose, the second provides usage context and return format. Information density is high 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 tool's complexity (4 parameters, no output schema), the description adequately covers the return format (ranked list with score, confidence, signal density). It also explains the optional model and context parameters. The description is complete for an agent to understand what the tool does and what it 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% with descriptions for all 4 parameters. The description adds value by clarifying that the first entity in the array is treated as the 'subject' for narrative purposes, and by explaining the relationship between models and _apiKey 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 the tool compares AI visibility across multiple entities side-by-side, with specific verbs ('compare', 'probes', 'ranks') and resources ('AI visibility', 'entities'). It distinguishes itself from siblings 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?

The description explicitly frames the use case ('competitive AI-marketing audits') with an example question, implying when to use. It does not explicitly state when not to use or name alternatives, but the sibling list provides context for single-entity checks via ai_visibility_check.

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

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

Annotations already cover readOnly, openWorld, idempotent, non-destructive. Description adds valuable behaviors: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed will list timeouts, rest still returns. No contradictions.

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

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

Description is well-structured with front-loaded purpose, then usage, then behavior details. It is informative but slightly lengthy; could be trimmed slightly 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?

No output schema, but description comprehensively explains return fields (summary block with is_latest, license, etc.), per-advisory detail, links, recent alternatives, and error handling for partial failures. Complete for a composite tool.

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

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

Schema coverage is 100%, but description adds meaning: package accepts scoped names like '@types/node', version defaults to latest when omitted. These details are not in 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 tool's purpose: composite check for adding npm packages, aggregating data from deps.dev and bundlephobia. Specifies verb 'check' and resource 'npm package', distinguishing from siblings by noting other ecosystems fall under deps.dev:version directly.

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

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

Provides explicit when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me". Also specifies scope: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', indicating alternatives.

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

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

Adds value beyond annotations: specifies BGE-base-en embeddings, 500-char overlapping windows, 200K char cap with truncation flag, and return fields (offsets, scores). No contradiction with annotations (readOnlyHint=true consistent).

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?

Efficient single paragraph, front-loaded with core purpose, every sentence adds value. 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?

Complete given no output schema: explains internal mechanics, constraints, and output characteristics. Annotations cover safety aspects. Pairs well with sibling 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 covers all parameters. Description adds practical context for 'text' (pass text already pulled) and 'query' with examples, 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?

Clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource. Distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and use case of large records.

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 (record too big for prompt) and pairs with ask_pipeworx_grounded. Provides details on limiting context and returning relevant passages with offsets.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive traits. The description adds value by specifying the external source (packagephobia.com) and the exact output (publish size and full install size in bytes), which are not captured by 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 sentence that efficiently conveys the tool's purpose and output. It is front-loaded and contains no unnecessary words.

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

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

Given the simple nature of the tool (2 parameters, with output schema present), the description is complete. It covers the input, output, and data source without requiring further elaboration.

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 does not add additional meaning beyond what the schema already provides for the two parameters (package, version). It simply restates that an optional version can be specified.

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 (Return), the resource (publish size and full install size in bytes for an npm package), and the source (packagephobia.com). It is specific and distinguishes this tool from siblings by focusing exclusively on npm package size retrieval.

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 obtaining npm package sizes with an optional version, but does not explicitly state when to use or not use this tool versus alternatives. No exclusions or context-specific guidance is provided.

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

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

The description conflicts with annotations: the idempotentHint annotation is true, but the description implies each call creates a new subscription (by returning a new subscription id), which is not idempotent. The description should clarify idempotency behavior or the annotation should be false.

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 comprehensive without unnecessary words. It front-loads the core purpose and return value, then logically follows with requirements, types, and delivery details. 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?

The description covers prerequisites, type-specific parameters, and delivery channels in detail. However, it does not specify the exact return format beyond 'subscription id,' and given the complexity of the tool, a bit more detail on the return object (e.g., status) would improve completeness. Nevertheless, it is largely adequate.

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

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

The description adds significant value beyond the input schema by providing detailed examples and constraints for each type-specific params and delivery channels (e.g., SMS cap, webhook signing). Schema coverage is 100%, but the description enriches understanding.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It differentiates from sibling tools like list_subscriptions and recent_alerts by focusing on creation of persistent subscriptions.

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

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

The description provides clear usage context, including the requirement for a Pipeworx OAuth account, supported subscription types with examples, and delivery channel options. It does not explicitly state when not to use the tool, but the context is sufficient for an agent to determine appropriateness.

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 idempotentHint=true, indicating safe, read-only behavior. The description adds significant context: it returns example questions drawn from the live catalog, includes the exact tool and argument shape, and can be called with no arguments or a topic for focused results. 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 a single paragraph but well-structured, starting with common query variations, then stating its purpose, return type, and usage. Every sentence adds value, though it is slightly long. It could be more concise, but 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?

Without an output schema, the description adequately explains what is returned (category-bucketed example questions with exact tool+argument shape). It covers all necessary context: purpose, usage, parameter, and output. For a discovery tool with one optional parameter, this 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?

The input schema has 1 parameter (topic) with a description listing valid values. Schema coverage is 100%, so baseline is 3. The description adds value by providing concrete examples of topic values ('finance', 'pharma', 'betting') and clarifying that omitting topic gives a full spread. This justifies a score of 4.

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

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

The description clearly states the tool is the onboarding entry point for an agent to discover what questions to ask Pipeworx. It specifies the return type (category-bucketed example questions with tool+argument shape) and distinguishes itself from sibling tools like ask_pipeworx and entity_profile by being the first tool to use when unfamiliar with the system.

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 instructs to 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also provides guidance on when to use the optional topic parameter for focus, and implicitly contrasts with sibling meta-tools by saying it teaches how to call them.

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 discloses ownership enforcement, deactivation (not deletion), and that historical events persist via 'recent_alerts'. 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?

Three concise sentences, no waste. First sentence states purpose, second adds constraint, third explains behavior. Front-loaded 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?

For a simple tool with one parameter and existing annotations, the description covers purpose, constraints, and side effects. It references sibling tools ('subscribe', 'recent_alerts') for context, 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% with a clear description for the 'id' parameter. The description adds minimal extra value, only noting the id comes from 'subscribe'. Baseline of 3 is appropriate given high coverage.

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

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

The description uses a specific verb 'cancel' and resource 'subscription by id', clearly distinguishing from siblings like 'subscribe' and 'list_subscriptions'. The ownership enforcement and deactivation behavior add further clarity.

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

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

Explicitly states ownership enforcement ('only cancel your own subscriptions'), guiding when the tool is usable. Contrasts with deletion by noting deactivation, which helps agents understand the effect. No explicit alternative mentioned, but context is strong.

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, idempotentHint, and destructiveHint false, indicating safe, idempotent behavior. The description adds value by disclosing the internal pipeline (NL parsing → entity resolution → data lookup → numeric comparison), the data source (SEC EDGAR + XBRL), and the return structure (verdict categories, structured form, actual value with citation, percent delta). This goes beyond the annotations without contradiction.

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

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

The description is relatively concise for its content, with all sentences serving a purpose: first defines the tool with trigger phrases, second gives usage instruction, third specifies domain, fourth outlines output, fifth notes efficiency gain. Could be slightly tighter, but 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's complexity (natural-language claim → structured verdict), the description is complete: it explains what the tool does, when to use it, what types of claims it handles, what the output looks like, and why it's efficient. Even without an output schema, the description covers return components sufficiently for an agent to evaluate and invoke the tool correctly.

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

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

The input schema covers the single 'claim' parameter with full description (100% coverage). The description reinforces this with natural-language examples and clarifies acceptable formats (e.g., 'Apple's FY2024 revenue was $400 billion'). This adds meaningful guidance beyond the schema's technical definition.

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: natural-language claim verification against authoritative sources. It provides trigger phrases like 'Is it true that…' and 'fact check,' and specifies the domain (company-financial claims for public US companies). This clearly distinguishes it from siblings like deep_research or ask_pipeworx_grounded.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and defines the scope (company-financial claims). It notes that the tool replaces 4–6 sequential calls, implying efficiency benefits. However, it does not explicitly state when not to use it or list alternative tools for other types of claims, which prevents a perfect score.

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