nutrition

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

Annotations already declare readOnly and idempotent hints. Description adds valuable context: scoring breakdown per model, combined view, pricing model (free default, BYO key for Anthropic). 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?

Three well-structured sentences: core purpose and output, model/pricing details, use cases. Front-loaded, no redundant 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 parameters (4, required 1) and no output schema, description sufficiently explains input, output (per-model + combined), and usage context. Complete for a probe tool.

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

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

Schema already covers all parameters with descriptions (100% coverage). Description adds context about model options, API key pass-through, and context disambiguation, reinforcing schema information.

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

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

The description uses a specific verb ('Probe') and resource ('LLMs'), clearly states it scores visibility (0-100) per model, and distinguishes from siblings by mentioning default model and optional Anthropic key.

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) and explains model selection (default free, Anthropic requires key). Lacks explicit when-not-to-use or direct comparison to similar sibling tools.

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

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

The description adds behavioral context beyond annotations: it routes to 4,774 tools across 1,242 sources, fills arguments, and returns structured answers with stable citation URIs. Annotations already indicate readOnly, openWorld, idempotent, non-destructive; description complements this 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 well-structured with a key front-loaded instruction ('PREFER OVER WEB SEARCH') and clear separation of use cases. It is somewhat lengthy but every sentence adds value; could be slightly more concise but remains 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 and the absence of an output schema, the description thoroughly explains what the tool does, how it works, and what it returns (structured answer with citations). It covers the necessary context for an AI 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 clear descriptions for all parameters, including aliases. The description provides examples but does not add significant new semantic meaning beyond the schema. Baseline 3 is appropriate as schema covers the need.

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 routes questions to authoritative structured data sources across many domains. It uses specific verbs ('routes', 'fills arguments', 'returns') and distinguishes from siblings like ask_pipeworx_grounded and deep_research, making the purpose unambiguous.

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

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

Explicitly states 'PREFER OVER WEB SEARCH' and provides detailed when-to-use scenarios (factual questions, real-world entities, events, numbers) and when-not-to-use (step up to grounded or deep research for specific needs). Also gives examples, making usage guidance comprehensive.

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 the annotations: it explains the 'grounded' mechanism (uses ONLY the tool result), specifies the exact return format including refusal reasons, and discloses the cost trade-off (one extra LLM call). There is 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 moderately lengthy but well-structured and front-loaded with key information (purpose, mechanism, return format, usage guidance, cost). Every sentence serves a distinct purpose, though minor tightening 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?

Given the tool's complexity (grounded answering, multiple refusal modes, no output schema), the description covers all essential aspects: what it does, how it works, when to use it, what it returns, and performance implications. It is self-contained and actionable.

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 6 parameters described in the schema. The description does not add new semantic information beyond labeling them as aliases for 'question'. Baseline 3 is appropriate since the schema carries full documentation burden.

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

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

The description clearly identifies a specific verb and resource: it provides 'hallucination-resistant answer mode' for 'high-stakes reads' and explains the routing and data extraction process. It effectively distinguishes itself from its sibling 'ask_pipeworx' by contrasting use cases (high-stakes vs casual 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 states when to use this tool ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and provides concrete examples (financial verdicts, legal claims, medical lookups). It also recommends preferring the sibling 'ask_pipeworx' for casual lookups, giving clear exclusion criteria.

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

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

The description extensively discloses behavioral traits beyond annotations, including resolution confidence (short-circuit on low confidence), handling of closed markets, wide-spread markets, fan-out examples per category, response shapes (market, analysis, evidence), resolver contract, parent event extraction, news fallback behavior, and resolution-rule risk. None of these are in annotations. The description does not contradict annotations.

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

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

The description is thorough but verbose, with multiple detailed paragraphs. It is front-loaded with purpose and use cases, but the sheer length (covering fan-out examples, response shapes, safety, etc.) reduces conciseness. While every section adds value, the overall length could be trimmed without losing critical information. Adequate but not concise.

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

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

Given the tool's complexity (no output schema, rich response), the description is extremely complete. It details all response sections (market, analysis, evidence, parent_event), edge cases (low confidence, closed markets, wide spreads, resolution risk), and provider-specific fields (news fallback). It covers everything an AI agent needs to invoke and interpret 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 already provides comprehensive descriptions for all three parameters (market, depth, include_raw) with 100% coverage. The description adds minimal new information about parameters, mostly giving examples of market input types and behavior of depth. With high schema coverage, the description's contribution to parameter semantics is limited, hence 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?

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 input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). The examples of use cases ('should I bet on X', etc.) further clarify its role. While it doesn't explicitly distinguish from siblings like 'ask_pipeworx' or 'polymarket_edges', the focused scope is evident.

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: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains how to pass input via examples. However, it does not explicitly state when not to use this tool or compare with alternatives like 'deep_research' or 'ask_pipeworx', which limits its differentiation.

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

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

The description adds significant behavioral context beyond what annotations provide. It explains that it makes one parallel call, details data pulled for each type (latest 10-K data for companies, FAERS data for drugs), mentions handling of off-calendar fiscal years, and states results are sorted by primary metric. This enriches the readOnlyHint, openWorldHint, and idempotentHint annotations.

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

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

The description is dense but front-loaded with common queries, making it immediately recognizable. Every sentence adds value, but it could be more structured (e.g., separated sections for company vs drug). Despite length, it remains efficient and to the point.

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 2 parameters, 100% schema coverage, no output schema, and moderate complexity, the description provides complete context: what data is returned (paired data + citation URIs), sorting behavior, and the scope (2-5 entities). It leaves no major gaps for an agent to 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?

Schema coverage is 100% with two parameters (type and values). The description goes beyond the schema by providing examples (tickers/CIKs for companies, drug names), constraints (max 5), and additional context like off-calendar fiscal year handling for company type. This adds meaningful 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 immediately links to common user queries like 'Compare X and Y' and clearly states it performs side-by-side comparison of 2-5 companies or drugs in a single parallel call. It distinguishes itself from sequential single-pack lookups, using a specific verb and resource.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups,' providing clear usage guidance. It also differentiates between company and drug types with specific data sources. However, it lacks explicit 'when not to use' guidance, though the sibling tools context implies alternatives.

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

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

Disclosures go well beyond annotations: account required (free/paid tiers), typical latency (15-60s), parallel decomposition across 4,774 tools, return format (findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[]), and explicit statement that it never invents. 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 long but front-loaded with critical constraints (account required, alternative for unsigned-in users). Every sentence adds necessary context. Minor redundancy (e.g., 'in ONE call' repeated) but overall efficient given complexity.

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

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

Despite no output schema, description fully describes return format (findings packet with evidence, confidence, source, fetched_at, citation, gaps[]). Parameter count is low (2) and covered. Context signals show high schema coverage. For a complex tool with annotations, the description leaves 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?

Input schema covers both parameters with descriptions (depth enum explains quick=3, standard=5, thorough=8; question as natural language). Description adds context about depth defaulting to standard and broad/multi-part questions being suitable. Schema coverage is 100%, so description adds marginal but useful nuance.

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: grounded multi-source research across 1242 structured data sources in one call. It distinguishes from sibling tools like ask_pipeworx by emphasizing broad/multi-part questions over structured data, 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 provides when to use (broad, multi-part structured questions) and when not to use (breaking news, single lookup). Mentions alternatives: ask_pipeworx for single lookups and news-based queries, and notes that deep_research returns empty gaps for topics not in the structured catalog.

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, so the description adds value by noting that results include 'full input schemas (with curated examples)' and that each result is 'ready to call directly'. This goes beyond the 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 longer than needed but each sentence adds value. It front-loads the purpose and usage, then details return format. Slightly verbose but not wasteful.

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

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

Given no output schema, the description adequately explains the return format (names, descriptions, schemas). It covers the discovery workflow, the types of queries, and the readiness of results. Sufficient for a discovery tool.

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

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

Schema coverage is 100% with each parameter described. The description adds that query accepts multiple aliases (task, q, description, search) and provides natural language examples, enriching the schema's 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 states 'Find tools by describing the data or task' with specific verb 'find' and resource 'tools'. It lists example domains (SEC filings, FDA drugs, etc.) and explicitly distinguishes this tool as the discovery entry point, differentiating it from sibling tools like search_products or deep_research.

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

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

Clear usage guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It provides an explicit when-to-use directive but does not list specific alternatives or when-not-to-use scenarios, though the context implies it's the initial discovery step.

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 read-only, open-world, idempotent, non-destructive hints. Description adds detail about patents API sunset and soft-fail behavior, and return sorting, which goes beyond annotations.

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

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

Description is long but well-structured, starting with example queries. Every sentence adds value, though it could be slightly more concise without losing information.

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

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

Given no output schema, description thoroughly explains return values (cik, filings, fundamentals, patents, news, LEI) and notes future changes (patents API sunset), making it 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?

Schema coverage is 100%, so parameters are already documented. Description adds examples and clarifies that names are not supported and to use resolve_entity, providing useful context beyond the schema.

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

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

Description clearly states the tool creates a 'full cross-source profile of a US public company in ONE parallel call,' lists data sources, and distinguishes from sibling tools like resolve_entity and chaining single-pack lookups.

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

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

Explicitly advises to 'ALWAYS PREFER over chaining single-pack... lookups when the user asks for a holistic view' and warns that names are not supported, directing to use resolve_entity first.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's 'delete' and 'clear' align. It adds value by specifying conditions for use (stale context, done task, sensitive data), 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?

Two sentences with zero wasted words. The action and use cases are front-loaded, making it easy for an agent to quickly understand 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?

For a simple deletion tool with one parameter and clear annotations, the description is fully complete. It covers purpose, usage, and relations to siblings without needing output schema.

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

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

Schema description coverage is 100% with a single parameter 'key' described as 'Memory key to delete.' The description does not add additional parameter-meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key.' This is a specific verb+resource pair, and it distinguishes from siblings like 'remember' and 'recall' by naming them explicitly.

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

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

The description gives explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data...' and suggests pairing with related tools, providing clarity on 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 indicate readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral specifics: fetches the page, extracts title/description/key links, and emits markdown. This goes beyond annotations, though some details like error handling or rate limits are omitted.

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 with a bullet list of use cases. Every sentence adds value, and the main action is front-loaded. No excessive wording.

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 explains the output format ('single text blob'), covers input (URL, max_links), process (fetch, extract), and explicit use cases. Complete for a simple tool.

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

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

Schema coverage is 100% with both parameters described. The description adds no extra parameter details beyond what the schema provides, so it meets the baseline without improvement.

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 generates an llms.txt file for a URL, using the specific verb 'generate' and resource 'llms.txt'. It explains the purpose for AI crawlers and distinguishes itself from sibling tools like 'scan_competitor_ai_presence' by focusing on production of the 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: getting a client's site indexed, drafting for own project, or auditing competitor. It lacks explicit 'when not to use' or direct comparison with siblings, but the listed use cases are clear enough for most scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds that it returns specific fields and defaults to active subscriptions only, which is useful 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?

Two concise sentences front-loading purpose and use case. 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?

Despite no output schema, description enumerates return fields. Tool is simple with one optional param, and all necessary context is provided.

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 provides 100% coverage for the single parameter (include_inactive) with description. Description does not add new information beyond the schema.

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

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

Clearly states it lists the caller's active subscriptions and specifies the returned fields. Distinguished from siblings like subscribe/unsubscribe by focusing on listing.

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: to review before adding more or to find an id to cancel. Implies alternatives (subscribe, unsubscribe).

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

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

Annotations provide basic hints, but the description adds critical behavioral details: rate-limited to 5 per identifier per day, free, doesn't count against quota, and the team reads digests daily affecting roadmap. 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?

Well-structured with purpose first, then usage details, then behavioral notes. Every sentence adds value. Slightly dense but not overly long; could be trimmed slightly 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?

Despite no output schema, the description covers what happens after submission (digests, roadmap impact) and sets expectations. For a feedback tool with two required params and clear schema, 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?

Schema coverage is 100%, but description adds significant nuance: explains each enum value for 'type', advises on message content (be specific, don't paste prompts), and clarifies 'context' is optional. This goes well 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 the tool is for sending feedback about bugs, missing features, data gaps, or praise. It uniquely identifies the tool's purpose among siblings, which are all query or action tools, making this the only feedback channel.

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 specifies when to use (bug, feature, data_gap, praise) and what not to do (don't paste user prompts). Contrasts with other tools implicitly by focusing on feedback vs. queries. Also mentions rate limits and free usage.

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

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

Annotations already mark it as readOnly, openWorld, idempotent, and non-destructive. The description adds useful behavioral context: self-aggregating signal, no PII, and caching behavior (5min-1h). 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, each serving a purpose: what it returns, three use cases, implementation details. No fluff, front-loaded with most important info.

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

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

For a simple read-only tool with one optional parameter and no required output schema, the description fully covers purpose, usage, behavior, and implementation details (caching). Everything an agent needs.

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

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

Schema coverage is 100% for the single parameter 'window' with enum and description. The description adds value by explaining the semantic difference between shorter and longer windows (hot vs steady-state), 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 uses specific verbs ('returns') and clearly states the resources: top tools, top packs, and total call volume. It distinguishes itself from siblings like 'discover_tools' by focusing on trending data derived from agent call patterns.

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

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

Explicitly lists three distinct use cases (discovering hot data sources, confirming canonical tool, checking alignment). While no direct when-not or alternatives are mentioned, the context is clear and actionable for an AI agent.

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

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

Annotations already show readOnlyHint, idempotent, not destructive. The description adds valuable behavioral context: it explains the algorithms (monotonicity violations, partition-sum checks), the semantic anchor, partition filter, and fill check with realizable edge conditions. 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 relatively long but well-structured with clear sections and examples. It is front-loaded with the purpose and uses bullet-like formatting. Every sentence adds value, though it could be slightly more concise. Still, it earns a high score for being informative.

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 modes, algorithms, response fields, fill check), the description is remarkably complete. It explains the response format (opportunities array, partition_check, suggested_trade) and references the sibling tool polymarket_fill_risk for custom sizing. No output schema exists, but the description compensates well.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema. It explains the default behavior with no args, what each parameter does in detail (e.g., event accepts slugs and URLs, topic searches related events), and the internal processing. This greatly aids proper parameter selection.

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.' This is a specific verb+resource+method, and it distinguishes itself from sibling tools like polymarket_edges or 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?

The description provides explicit guidance: call with no args for trending scan, pass 'event' for single-event partition check, or 'topic' for cross-event scan. It recommends 'event' for specific markets and explains the differences, making it easy for the agent to decide.

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

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

The description discloses extensive behavioral traits beyond annotations: caching (1h at KV level), response structure with segments and diagnostics, edge calculation details, note about Fed bets being excluded (unreliability of certain signals), and filtering knobs. Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds substantial context without contradiction.

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

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

The description is thorough but verbose, with dense technical details that could be condensed. It is well-structured with sections for segments, knobs, and response format, but some sentences are overly complex (e.g., 'placeholder-slug filter drops will-person-X / will-team-Y / will-manager-Z / will-someone-else- backstops'). A more concise version would improve readability while retaining essential 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 9 parameters and no output schema, the description is highly complete. It explains the response structure (by_segment, fed_candidates, _diagnostics), caching behavior, why segments might be empty, and all filtering knobs are described with their effects. The description ensures an agent has enough context to use the tool effectively and interpret results.

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

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

Schema covers 100% of parameters with descriptions. The tool description adds value by explaining the logical groupings of parameters (e.g., 'TRADEABLE-EDGE KNOBS: min_liquidity / max_spread_pp drop opportunities where edge isn't realizable') and how certain parameters interact (e.g., min_partition_leg_kelly filters per-leg Kelly inside partitions). This provides semantic depth beyond what the schema alone offers.

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

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

Description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies the verb 'scan' and 'return', the resource (Polymarket markets), and the outcome (opportunities with edge). It also distinguishes the tool's purpose with the phrase 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' This directly differentiates from siblings like polymarket_arbitrage which focus on different strategies.

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

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

The description provides clear context for when to use the tool: discovering betting opportunities without manual browsing. It explains that the tool is for exploring edges based on model-driven, structural arbitrage, and concentrated longshot strategies. However, it does not explicitly state when not to use this tool vs alternatives like polymarket_arbitrage, but the context is strong enough to infer appropriate use cases.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds important behavioral details such as history depth bounded by 60-day TTL, decay numbers coming from daily closes not intraday, and gaps meaning no scan that day. 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 structured with clear sections: purpose, args, response fields, and limits. It is slightly verbose but every sentence adds value. Could be tightened without losing information.

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

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

Despite having no output schema, the description thoroughly explains the return structure (tracked, expired, snapshot_dates) with field meanings and caveats. For a tool of this complexity, it provides all necessary context for correct usage.

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

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

Schema coverage is 100%, but the description adds meaning beyond schema types by explaining the default and maximum for 'days' and the concept of 'snapshot family' for 'window'. It provides context that helps an agent choose appropriate 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 provides edge persistence and decay telemetry, answering how long an edge has existed and if it's shrinking. It uses specific verbs like 'answers' and distinguishes itself from sibling tool 'polymarket_edges' by focusing on time-series analysis rather than single snapshots.

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

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

The description provides context on when to use this tool ('a fresh wide edge and a 3-week-old wide edge are different trades') and explains the trade-off. However, it does not explicitly state when not to use it or name alternatives, though the sibling list implies polymarket_edges for single-snapshot 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?

Adds significant behavioral context beyond annotations: explains required modes (market vs event), data sources (live CLOB order-book depth), return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and risk of partial fills converting arb to unhedged position. 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 dense with information and every sentence adds value, but it is relatively long and could benefit from clearer structure (e.g., bullet points for modes and return fields). However, it remains readable and front-loaded with the 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?

Despite lacking an output schema, the description enumerates all return fields in detail (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk) and covers edge cases and risks, making it fully self-contained.

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

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

Schema coverage is 100%, but the description adds substantial meaning: explains what size_usd represents for single-market vs basket, side defaults and behavior, and the distinction between market and event parameters. Goes well 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 defines the tool as a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes with specific verbs and resources. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by stating its role as a prerequisite check.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also warns about risks of partial basket fills, providing clear context for 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details how the spread is computed, what temporal alignment means, and what triggers compatibility warnings (e.g., mismatched bet shapes or semantically unrelated events). It also explains counters for dropped comparisons, providing deep 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 well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the main purpose. However, it is somewhat verbose; a minor trim could improve conciseness without losing essential details.

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

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

Despite no output schema, the description fully describes the response structure (prices, spread, compatibility_warning, temporal_alignment, skip counters) and covers edge cases. An agent can understand what to expect and when the results are meaningful.

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 description still adds value by explaining the two modes, listing the 10 topic shortcuts with examples for explicit parameters, and clarifying how explicit parameters override topic.

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. It uses specific action and resource, and distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue rather than intra-venue.

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 explains two modes (topic shortcuts and explicit event tickers), provides a list of pre-mapped shortcuts, and warns that most shortcuts currently return compatibility warnings, guiding when the tool is useful. It also explains response fields like compatibility_warning to help interpret results.

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, which the description matches (retrieve operation, non-destructive). The description adds scoping to identifier (anonymous IP, BYO key hash, account ID), providing valuable behavioral context beyond annotations. No contradictions.

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

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

The description is two sentences, front-loaded with core function. No unnecessary words. The structure places primary purpose first, then additional context and pairing. 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?

For a simple tool with one optional parameter and full annotation coverage, the description is complete. It explains the data source ('remember'), scoping, and the ability to list all keys. No output schema is needed, and the context 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?

Input schema covers 100% of parameters with description for 'key'. The description restates that omitting key lists all keys, which matches schema. It does not add new semantic detail beyond what schema provides, so 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 retrieves a value saved via 'remember' or lists all keys. It specifies the resource (saved values) and action (retrieve/list). The examples and pairing with 'remember' and 'forget' further clarify its role, distinguishing it from 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?

The description explicitly says to use when the agent needs to look up previously stored context without re-deriving it. It mentions pairing with 'remember' and 'forget', but does not explicitly state when not to use or provide alternative tools. However, the context is clear and sufficient for a simple tool.

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

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

Annotations indicate readOnlyHint, idempotentHint, and destructiveHint=false. The description adds that setting mark_read:true flags events as read, altering state for future calls. This is transparent about the side-effect, with no contradiction to annotations.

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

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

The description is three sentences, front-loaded with purpose, and each sentence adds distinct value (function, returned fields, filtering, mark_read effect, alternative access). No wasted words.

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

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

Despite no output schema, the description explains what is returned and covers all parameters. It mentions alternative access for scripts/dashboards and confirms polling works, making it self-contained for a read 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?

Parameter schema has 100% description coverage. The description adds context beyond the schema by mentioning filter examples ('sec_8k'), explaining mark_read behavior, and clarifying the format for 'since' (ISO timestamp).

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 the specific verb 'pull' and clearly identifies the resource as 'fired events from your subscription feed', listing key fields like source, citation_uri, and raw payload. This distinguishes it from siblings like list_subscriptions or recent_changes.

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

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

It explains the tool retrieves recent alerts and mentions polling works fine, with an alternative endpoint (GET registry.pipeworx.io/alerts.json) for scripts and dashboards. It does not explicitly state when not to use, 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, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds significant behavioral context: parallel fan-out to three sources, fallback strategy, soft-fail for USPTO, and output structure (changes[], total_changes, citation URIs).

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 dense single paragraph that front-loads example queries. Every sentence adds value, covering sources, fallbacks, parameter details, and output. Minor improvement possible with structural breaks, but it remains concise and informative.

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

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

Despite no output schema, the description sufficiently explains the output structure (changes grouped by source, total_changes count, URIs). It covers edge cases (fallbacks, soft-fail) and is complete for the tool's complexity (3 parameters, no nested objects).

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. Description adds extra value by explaining how to use 'since' with relative shorthand examples, clarifying that 'value' accepts ticker or CIK, and recommending typical monitoring intervals. This goes 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?

Description explicitly states the tool provides a change feed for a company, covering SEC filings, news, and patents in one parallel call. It includes example queries like 'What's new with X' and clearly 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?

Description provides explicit guidance on when to use this tool (change feed queries) versus entity_profile (static profile). It also details fallback behavior (GDELT→GNews), parameter usage (since as ISO date or relative shorthand), and even recommends typical values like '30d'.

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 critical context beyond annotations: scope ('scoped by your identifier'), persistence ('authenticated persistent, anonymous 24 hours'), and that it's a key-value store. 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?

Four sentences, front-loaded with purpose, no redundancy. Every sentence adds value.

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

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

Fully covers all aspects for a simple two-param tool: scope, persistence, usage context, and sibling tools. No output schema needed.

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 3. Description adds value with examples but doesn't significantly expand on 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?

Clearly states the tool saves data for reuse across sessions, using specific verb 'save' and resource 'data'. Distinguishes from siblings by mentioning 'recall' and 'forget'.

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

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

Explicitly says when to use ('when you discover something worth carrying forward') and provides examples. Implicitly covers when not by suggesting pairing with recall/forget for retrieval/deletion.

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

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

Annotations already indicate safe read-only, idempotent behavior. Description adds that each call cascades through several endpoints internally, replacing 2-3 manual lookups, giving insight into performance and scope.

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

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

Well-structured with examples, usage note, and supported types. Slightly long but every sentence is informative. Front-loaded with common queries.

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 fully details return values for both entity types (ticker, CIK, company_name, citation URI for company; RxCUI, ingredient, brand, citation for drug), making it self-contained.

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

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

Schema coverage is 100%, baseline 3. Description adds value by explaining the exact formats for 'value' per type (e.g., ticker, CIK, name for company; brand or generic for drug) and clarifies the returned 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?

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with specific examples like ticker, CIK, and RxCUI. It distinguishes itself from sibling tools by being a first-step lookup 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 says 'Use FIRST whenever you have a name but need an ID.' Provides concrete examples of when to use. Could mention when not to use or 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 the tool as read-only, idempotent, and non-destructive. The description adds details about probing with ai_visibility_check, ranking by score, and returning specific metrics (score, confidence, signal density), enhancing transparency 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 three sentences long, front-loaded with the core action in the first sentence. It is concise, with no redundant or unnecessary words, and effectively conveys the tool's purpose and behavior.

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 four parameters, no output schema, and comprehensive annotations, the description adequately explains the tool's functionality, return format, and a typical use case. It could mention potential limitations or error conditions, but it is sufficiently complete for the complexity level.

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

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

The input schema provides full descriptions for all parameters. The description adds contextual meaning, such as that the first entity in entities is treated as the subject for narrative and that context disambiguates common names, which helps the agent understand parameter intent 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 compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and returns a ranked list. It distinguishes from sibling ai_visibility_check by emphasizing side-by-side 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 provides a clear use case (competitive AI-marketing audits) and a concrete example question. It does not explicitly state when not to use, but the context implies it is for comparative analysis. It does not mention alternatives like ai_visibility_check for single probes.

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 behavioral details beyond annotations: '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, the rest still returns.' 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 a single paragraph, front-loaded with the core composite nature. Every sentence adds value, though it could be slightly more structured (e.g., bullet points for return fields). It is concise given the complexity.

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

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

No output schema, but description details the return block (summary fields, per-advisory detail, links, alternative versions). Covers ecosystem scope and partial failure handling. Given the tool's complexity, the description is complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context: 'Scoped packages (e.g. @types/node) are accepted' and 'Specific version to check... Defaults to the latest published version when omitted.' This adds value beyond schema, justifying a 4.

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

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

The description clearly states the tool's purpose: a composite check for npm packages using deps.dev and bundlephobia. It uses specific verbs ('fans out across') and identifies the resource ('npm package'). It distinguishes itself from siblings by focusing on this composite functionality, which is unique among the listed siblings.

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

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

Explicit guidance on when to use ('is X safe / popular / small' or 'what does adding lodash cost me'). Also provides alternatives: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This helps the agent decide when not to use this tool.

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

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

Adds substantial behavioral details beyond annotations: returns passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine similarity on 500-char overlapping windows, caps input at 200K chars with truncation flag. Annotations already indicate read-only, idempotent, non-destructive; description complements 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?

Concise yet comprehensive; front-loaded with core purpose, followed by usage guidance, technical details, and pairing. Every sentence is meaningful with no redundancy.

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

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

Despite no output schema, the description fully explains expected output (top-N passages with offsets and scores), technical implementation (chunking, embedding model, character cap), and use case context. Complete for a moderately 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 description coverage is 100% with good parameter descriptions. The description reinforces the text parameter as 'already pulled record' and provides query examples, but this adds minimal new meaning beyond the schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource. It distinguishes from siblings by specifying the use case for large records and explicitly pairing with ask_pipeworx_grounded.

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

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

Explicitly advises 'Use when the record is too big to cram into the prompt' and suggests pairing with ask_pipeworx_grounded for grounded generation, providing clear guidance on when and how to use the tool.

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

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

Adds extensive behavioral context beyond annotations: requiring OAuth account, delivery channel constraints, and webhook auto-disable. 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?

Well-structured with bullet points, but slightly lengthy. Could be more concise without losing essential details.

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

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

Covers all aspects: required auth, types, params, delivery channels, and limitations. No output schema but sufficient given 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 description adds detailed examples and explanations for all parameters, especially the nested params and delivery objects.

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

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

Clearly states it creates a proactive monitoring subscription, distinguishing from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides explicit prerequisites, supported types, and delivery channel options, but does not explicitly state when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds context: returns category-bucketed examples drawn from a live catalog, with optional topic filtering. No contradictions. Adds value beyond annotations by describing the non-obvious return structure.

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 common user queries, then clear purpose, output description, and usage note. Somewhat lengthy but every part serves a purpose for an onboarding tool. Could be shortened slightly but remains 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 the tool's simplicity (1 optional param, no output schema) and rich annotations, the description covers purpose, usage, parameter, output format, and when to use. Missing details on exact response format but sufficient for 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 covers the only param 'topic' with description listing allowed values. Description reinforces by giving examples like 'finance', 'pharma', 'betting' and explains effect: 'to focus'. Adds context beyond schema.

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

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

Explicitly states it is the onboarding entry point for an agent to learn what Pipeworx can do, distinguishing it from siblings like ask_pipeworx which answer specific questions. Uses specific verbs: 'returns category-bucketed example questions' and 'learn how to call the meta-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?

Clearly indicates when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you or to learn how to call the meta-tools.' Also implies not to use when you already have a specific question, as that would be for ask_pipeworx. Provides 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 show readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds context about ownership enforcement and that the row is deactivated (not deleted) to preserve historical events. No contradiction with annotations.

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

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

Two sentences with no wasted words. Front-loads the action and then provides key behavioral details. Perfectly concise.

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

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

For a simple cancellation tool with one parameter, no output schema, and explicit annotations, the description covers ownership, deactivation behavior, and historical data availability. 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% with one 'id' parameter described as 'Subscription id (uuid) returned by subscribe.' The description adds minimal extra meaning beyond the schema, just referencing the source of the id. 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 verb 'Cancel' and the resource 'subscription by id'. It also explains the effect (deactivate, not delete) and distinguishes from siblings like 'subscribe' and 'list_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 explicitly says 'you can only cancel your own subscriptions', which informs when to use the tool. It does not explicitly mention when not to use it or provide alternatives, but the ownership rule is clear enough for proper usage.

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

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

Annotations indicate readOnly, idempotent, and non-destructive behavior. The description adds value by detailing the underlying data sources (SEC EDGAR + XBRL), the verdict types returned, and the citation format, giving agents a clear understanding of the tool's mechanics.

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

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

The description is well-structured, starting with example triggers, then usage context, domain scope, and return details. While slightly verbose, every sentence adds value, and it is front-loaded with the 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 simplicity (one parameter, no output schema), the description fully explains inputs, domain, return values, and what the tool replaces. It is complete and leaves no ambiguity for an agent to select 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?

With only one parameter and 100% schema description coverage, the schema already explains 'claim' as a natural-language string. The description enhances this by providing concrete examples and specifying the domain, adding practical guidance 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 defines the tool's purpose: natural-language claim verification against authoritative sources, specifically for company-financial claims. It provides example phrases and differentiates it from sibling tools by specifying the domain and return types.

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

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

The description explicitly states when to use this tool ('whenever the agent needs to check whether something a user said is factually correct') and delimits the scope to company-financial claims. It does not provide explicit alternatives or when-not-to-use, but the domain restriction is clear.

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