Owid

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds beyond that: scoring range (0-100), per-model response fields (score, confidence, signals, raw_response), combined view, and cost implications for Anthropic (user pays). 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 with no filler. Key information is front-loaded: the primary action and output. Every sentence adds value, explaining model choice, key requirements, return format, and use cases.

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 four parameters and no output schema, the description adequately covers input semantics, model behavior, return structure, and use cases. Annotations cover safety. The tool is well-specified for an AI agent to understand and invoke correctly.

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

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

Schema coverage is 100% (all parameters have descriptions). The description adds further context: entity examples, default model, condition for _apiKey requirement, and the purpose of context for disambiguation. This meaningfully extends 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 awareness and returns a visibility score (0-100). It uses a specific verb ('probe') and resource ('LLMs'), and the output format is outlined. The tool is distinct from siblings like 'ask_pipeworx' or 'scan_competitor_ai_presence' due to its focus on multi-model scoring.

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

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

The description gives explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains model options (free default vs. paid Anthropic). However, it does not explicitly state when to prefer this tool over simpler alternatives like 'ask_pipeworx', though the scoring aspect implies primary 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, and destructiveHint. The description adds context about routing to multiple tools and returning structured answers with citation URIs, which is 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 somewhat lengthy but front-loaded with key guidance. It is well-structured and earns its length by covering many use cases and sibling differentiations.

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 (4482 tools, many sources, no output schema), the description is remarkably complete. It explains what the tool does, how it works, and how it relates to siblings, leaving little ambiguity.

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

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

Schema coverage is 100% with descriptive parameter names and aliases. The description adds examples but does not significantly enhance understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description specifies the tool's purpose clearly: it answers factual questions using structured data from many sources, with citations. It distinguishes from sibling tools like ask_pipeworx_grounded and deep_research by stating when to use each.

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 extensive guidance on when to use this tool (prefer over web search for factual questions) and when to step up to siblings (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad multi-part questions). It also includes many example 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?

Annotations already provide readOnlyHint, openWorldHint, etc. The description adds valuable context: costs an extra LLM call, returns structured output with evidence and refusal reasons, and explains that it refuses if data doesn't directly answer. 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 slightly lengthy but every sentence adds critical information. It is well-structured, starting with purpose, then behavior, then usage guidance, and ends with cost trade-off. Could be slightly more terse but overall efficient.

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

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

Given no output schema, the description fully compensates by detailing the return format (answer, evidence, confidence, source, etc.) and all possible refusal reasons. For a complex tool with 6 parameters and high-stakes usage, 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%, so baseline is 3. The description adds value by listing aliases (query, q, prompt, text, input) and clarifying that the question parameter accepts natural language. This helps the agent understand parameter flexibility.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and explains the process: routes to the right tool, fetches data, extracts answer only from tool result. It distinguishes from sibling 'ask_pipeworx' by naming it as the grounded version.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Gives examples (financial verdicts, legal claims, medical lookups). Also explicitly prefers 'ask_pipeworx for casual lookups.'

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

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

The description goes far beyond annotations (readOnlyHint, idempotentHint, destructiveHint) to disclose detailed behavior: fan-out patterns per category, response shapes, resolver contract with confidence levels, parent_event extraction, news fallback fields, safety mechanisms (low-confidence stubbing, closed markets), spread liquidity warnings, and resolution-rule risk. 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 very long and detailed, with multiple paragraphs and sections (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.). While structured and front-loaded with the main purpose, it could be more concise. Every sentence adds value, but the length may overwhelm some agents.

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 output structure (result.market, result.analysis, result.evidence, etc.), covers edge cases (low confidence, closed markets, wide spreads), safety behaviors, and resolution-rule risk. For a complex tool with 3 parameters and extensive fan-outs, the description is very 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% (3 parameters described). The description adds substantial meaning: explains market parameter accepts slug, URL, or question text; depth parameter defines 'quick' vs 'thorough'; include_raw describes impact on response size. Examples in schema and description clarify usage 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's core function: '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 components (evidence packet + market-vs-model comparison). The 'Use for' examples differentiate it from sibling tools like polymarket_edges and polymarket_arbitrage.

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

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

The description provides explicit use cases ('Use for "should I bet on X"...') and extensive examples of classifiers and fan-outs. It also includes guidance on inspecting result fields before trusting analysis. However, it does not explicitly state when not to use the tool or name alternatives, though the context of sibling tools implies differentiation.

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

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

Annotations declare read-only, idempotent, non-destructive. Description adds specifics: pulls latest 10-K financials with correct fiscal year handling for companies, FAERS counts for drugs, results sorted by primary metric, returns citation URIs. Full 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?

Every sentence adds value despite length. Front-loaded with example queries, progresses logically to what data is returned. No redundant phrases; efficient 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?

For a comparison tool with 2 parameters and no output schema, the description covers all necessary context: data sources, sorting behavior, output format, handling of fiscal year variations, and replaces many sequential lookups. Completeness is high.

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

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

Schema coverage is 100% with basic descriptions. Description adds significant meaning: for 'type' explains data sources (SEC EDGAR/XBRL, FAERS), for 'values' provides naming conventions (tickers/CIKs vs drug names) and examples. Greatly enriches 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 clearly states the tool compares 2-5 companies or drugs side-by-side, with specific verbs like 'compare', 'X vs Y', and distinguishes from siblings by emphasizing one-call comparison vs sequential 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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving clear when-to-use guidance. Also implies not for single-entity lookups, referencing 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?

The description adds behavioral context beyond annotations: not open-web search, returns gaps[] when data unavailable, expected 15-60s execution, and never invents data. Annotations include readOnlyHint=true, openWorldHint=true, which align with description. 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 thorough but not overly verbose. It is well-structured with critical info (account required, alternative) at the beginning. Every sentence serves a purpose, though the length could be slightly reduced for conciseness 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?

Given no output schema, the description compensates by detailing the return format: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, and gaps[]. It also covers account requirements, execution time, and when to expect empty results. 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% with descriptions, but description adds value: explains depth values map to number of facets (quick=3, standard=5, thorough=8) and clarifies 'thorough' requires paid plan. For question, it reinforces that broad/multi-part is fine. Adds meaning beyond schema.

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

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

The description clearly states it performs 'Grounded multi-source research across Pipeworx's 1129 STRUCTURED data sources' and distinguishes itself from sibling ask_pipeworx by noting it decomposes questions into facets and routes to tools in parallel. The verb 'research' and specific resource 'structured data sources' provide clear 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?

Explicit guidance on when to use: 'Best for broad/multi-part questions over structured data' and when not: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also mentions account requirements and depth limits.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that results include full schemas ready to call directly, no second lookup needed. Adds useful behavior detail 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 a single paragraph with logical flow: purpose, usage, details. Slightly verbose but every sentence adds value. Could be tighter but still 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?

Completeness is strong for a search/discovery tool. Description covers what the tool returns (names, descriptions, schemas, examples) and how to use it. No output schema, but description clarifies return format adequately.

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

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

Schema coverage is 100%, and the description reiterates the query parameter's purpose with examples. Doesn't add significant new meaning beyond what the schema and examples already provide.

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 'Find tools by describing the data or task' and enumerates specific domains (SEC filings, financials, etc.). Differentiates from siblings by positioning itself as the tool to call first for discovering options.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set' and provides concrete use cases like browsing/searching. Gives clear when-to-use 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 declare readOnlyHint and idempotentHint. The description adds valuable behavioral context: parallel cross-source fan-out, specific return fields, and the soft-fail note for patents. Does not mention rate limits or caching, but the added context is sufficient.

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 examples, well-organized into purpose, preference, and details. Slightly verbose but every sentence adds information. Could be trimmed slightly, but structure 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?

Despite no output schema, description thoroughly explains return fields (cik, filings, fundamentals, patents, news, LEI) and limitations (names not supported, patent soft-fail). Missing details on error handling or size limits, but covers main use case 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%, baseline 3. Description adds extra meaning by clarifying that type is only 'company' and value must be ticker or zero-padded CIK, with examples and recommendation to use resolve_entity for names, enhancing understanding beyond schema.

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

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

The description clearly states it provides a full cross-source profile of a US public company in one parallel call, with example queries. It distinguishes itself from siblings like compare_entities and resolve_entity by focusing on holistic single-entity profiles.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack... when user asks for holistic view' and advises using resolve_entity first if only a name is available, providing clear when-to-use and 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 indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds value by specifying the output format ('tidy long-format', rows of {entity, year, value}), the data sources (Maddison, Gapminder, etc.), and filtering capabilities. 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 yet comprehensive, with three front-loaded sentences covering core function, usage guidance, and return format. Every sentence contributes unique value. Examples are integrated naturally.

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 parameters are fully described, annotations cover safety and behavior, and the description adds output format, filtering details, and usage context, the description is complete for an agent to effectively select and invoke this tool.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds meaning beyond the schema by explaining the slug concept with examples, how country accepts name or ISO code, and how since_year/until_year work. It also shows example parameter combinations.

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 action ('Fetch tidy long-format data'), the resource ('Our World in Data indicator by slug'), and distinguishes from web search tools by explicitly recommending this for deep-historical data. It provides specific slug examples and 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 gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH for DEEP-HISTORICAL / LONG-RUN demographics and development data' and 'Use this for pre-1960 history that World Bank / current-population tools CANNOT answer'. It also provides concrete examples of queries that this tool should handle.

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 destructiveHint=true. The description adds context about why deletion is needed (stale context, sensitive data) and confirms the action is deletion, aligning with 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: one sentence stating the action, followed by usage guidance. 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 tool's low complexity (1 param, no output schema, has annotations), the description provides sufficient information for correct invocation and 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% with a clear description for the key parameter. The description restates 'by key' but adds no new semantic value beyond the schema.

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

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

The description clearly states 'Delete a previously stored memory by key.' It specifies a unique verb (delete) and resource (memory), distinguishing it 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?

Explicitly says when to use: when context is stale, task done, or to clear sensitive data. Also mentions pairing with remember and recall, providing clear usage 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?

Description adds details beyond annotations: it fetches the page, extracts fields, and emits standard markdown. Annotations already declare read-only and idempotent, so description complements them well.

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, front-loaded with purpose, process, and use cases. No superfluous words.

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

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

Covers purpose, process, output format, and use cases. Missing potential prerequisites or error scenarios, but overall 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 covers both parameters with descriptions. Description adds no new semantic detail for parameters beyond what schema provides, but provides context on output format and usage.

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

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

Clearly states it generates a production-ready llms.txt file for any URL, extracting title/description/key links. Distinguishes from siblings like ai_visibility_check by focusing on llms.txt output.

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

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

Explicitly lists three use cases (indexing client site, drafting for own project, auditing competitor). Does not mention when not to use or alternatives, but context is clear.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds value by detailing the specific metadata fields returned (including dates), which goes 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 sentences with zero waste. The first sentence front-loads the action and output; the second provides usage guidance. Every element 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?

For a tool with one required parameter, 100% schema coverage, and an output schema, the description is complete: it explains the purpose, usage, and expected output. No gaps remain.

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

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

Schema coverage is 100% with a single parameter 'slug' described as 'OWID chart slug' and an example. The description adds 'OWID indicator slug' but does not provide additional semantic meaning beyond what the schema already 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?

The description clearly states the tool fetches chart metadata for an OWID indicator slug, listing specific fields returned (title, subtitle, note, per-column details). This distinguishes it from siblings like fetch_indicator (which fetches actual data) and list_popular_indicators.

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

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

Explicitly instructs to use this tool to confirm a slug is valid and learn units before calling fetch_indicator. This provides clear when-to-use and when-not-to-use guidance, referencing a specific sibling.

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 that the list is curated and has deep-historical coverage for some series, 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?

Three sentences, front-loaded with the main action, and every sentence adds necessary information without fluff.

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

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

Given the presence of annotations, output schema, and simple parameter, the description provides complete context: what it does, how to use results, and limitations (not exhaustive).

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that the category parameter filters to common categories and that the returned data includes slug and title, which is helpful despite the schema already listing the enum.

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 lists curated Our World in Data indicators with slug and title for common categories, and distinguishes from sibling tools by directing to use the slug with fetch_indicator.

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 it covers common categories, is not exhaustive, and directs users to ourworldindata.org for full catalog. Also instructs to use the slug with fetch_indicator, which is a sibling tool.

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

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

Annotations already declare read-only, idempotent, and non-destructive. Description adds return fields but no additional behavioral traits beyond that, which is adequate.

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 no fluff. First sentence states purpose and returns, second gives usage guidance. Efficient and front-loaded.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers what the tool does, returns, and when to use it.

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

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

Schema covers the only parameter with description. Description adds context by implying default behavior (active only) before mentioning the include_inactive parameter. Adds value over 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?

Clearly states 'List the caller's active subscriptions' with specific verb and resource. Distinguishes 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 advises use for reviewing subscriptions before adding more or to find an id to cancel. Lacks explicit when-not-to-use, but context is sufficient.

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

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

Discloses key behavioral traits beyond annotations: rate-limited, free, doesn't count against quota. Annotations are all false, which is consistent with a write operation, and the description adds useful context about daily digests and roadmap impact.

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?

Every sentence is purposeful and earns its place. The description is front-loaded with the tool's core purpose, then details usage, constraints, and best practices. No filler or redundancy.

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

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

For a feedback tool with no output schema, the description is complete. It covers when to use, what to include, constraints (rate limits), and how feedback is processed. 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 description coverage is 100%, so baseline is 3. However, the description adds meaning by explaining each enum value in the type field (bug, feature, etc.) and offering guidance on message content (be specific, 1-2 sentences). This extra context justifies a 4.

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

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

The description opens with a clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It lists specific use cases (bug, feature, data_gap, praise) and distinguishes itself from sibling tools, none of which are feedback 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 states when to use (for bugs, feature requests, data gaps, praise) and what not to do (don't paste end-user prompt). Also provides rate limits (5 per identifier per day), cost (free), and quota impact (doesn't count).

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

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

Annotations already declare readOnlyHint, idempotentHint, and not destructive. Description adds value beyond annotations by explaining the data source (CF analytics-engine), absence of PII, and caching timeframes (5min-1h). 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?

Three sentences with front-loaded key result. Each sentence adds distinct value: what it returns, use cases, and behavioral notes. Zero waste.

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

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

No output schema, but description mentions 'top tools, top packs, total call volume' which gives adequate idea of return format. For a simple trending tool with good annotations, it's complete.

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

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

Schema coverage is 100% and description adds contextual guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds meaning beyond the schema's enum description.

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

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

The description clearly states the verb and resource: 'Returns the top tools, top packs, and total call volume over a recent window'. It distinguishes from siblings like 'discover_tools' and 'list_popular_indicators' by focusing on other agents' current calls on Pipeworx.

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

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

Explicitly lists three use cases: discovering hot data sources, confirming canonical tools, and seeing alignment with other agents. Also notes caching behavior and that it's self-aggregating signal without PII.

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

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

Annotations already indicate readOnly, openWorld, idempotent. The description adds extensive behavioral context: monotonicity checks, partition_sum verification, semantic anchor (Jaccard similarity), partition filter for placeholders, fill check against live CLOB depth, and trade recommendations. 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 well-organized with labeled sections (REQUIRES, SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It is front-loaded with the requirement. Every sentence adds value; no fluff. Length is appropriate for the tool's complexity.

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

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

Given the tool's complexity and lack of output schema, the description fully covers inputs, behavior, response structure (opportunities, partition_check), and important warnings (realizable_edge_pp, placeholder filtering). It also references a sibling tool for further actions. Sufficient for correct agent use.

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

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

Parameters have 100% schema coverage, but the description adds critical usage details: event accepts full URLs, topic expects a seed question, and cross-event mode requires Jaccard similarity. It also clarifies the functional difference between modes. Adds significant 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?

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between single-event and cross-event modes, and specifies the exact type of inputs (event slug or topic question). No ambiguity.

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

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

Explicitly advises when to use each parameter: event for a specific market, topic for cross-event scanning. It warns that calling with no args fails, and points to an alternative tool (polymarket_fill_risk) for custom sizing. Provides clear when-to-use and 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 readOnlyHint true, and the description adds extensive behavioral details: caching, model families, filter logic, slippage assumptions, and response structure beyond the annotations.

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

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

The description is long but well-structured with clear sections, front-loaded purpose, and every sentence adds value; minimal redundancy.

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

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

Given no output schema, the description fully explains response format, diagnostics, and ranking, covering all aspects needed 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?

All 9 parameters have schema descriptions (100% coverage), and the tool description adds extra context for some parameters (e.g., min_kelly, slippage_pp), enhancing understanding beyond the schema.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and it distinguishes from siblings like polymarket_arbitrage by focusing on edge detection via models.

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

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

The description explains the tool is built for 'what should I bet on today' and mentions tradeable-edge knobs, but does not explicitly contrast with sibling tools like polymarket_arbitrage or provide 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 indicate read-only and non-destructive behavior. The description adds valuable details: return structure (tracked, expired, snapshot_dates), computation of trend and decay, limits (60-day TTL, gap behavior), and that decay is from daily closes, not intraday. 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?

Despite length, the description is well-structured: opening with purpose, then detailing return fields and limits. Every sentence adds value, front-loads key info, and uses clear formatting (e.g., ARGUMENTS, RESPONSE sections).

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 fully explains the return structure and semantics. It covers tracked opportunities, expired ones, snapshot dates, and limitations like TTL and data gaps. No important aspect appears missing given the tool's scope.

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 context: defaults (14 days, '1wk'), max days (30), and enumeration of window families (24hr, 1wk, 1mo). This assists parameter selection 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: providing edge persistence and decay telemetry from daily snapshots. It answers the specific question of how long an edge has existed and its trend, and distinguishes this 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?

The description implies usage scenarios (fresh vs old edges) but does not explicitly compare to sibling tools or state when not to use it. It gives context on TTL and gaps, which helps, but lacks direct alternatives or 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 true and destructiveHint false, indicating a safe, read-only, idempotent operation. The description adds valuable behavioral context: it 'walks the ladder' and returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and explains basket mode return details including forced_directional_risk. 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 fairly long but well-structured with bold headers for modes and clear, logically organized sentences. Every sentence adds value without redundancy. Minor room for tightening, but overall effective and not overly verbose.

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

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

Despite no output schema, the description thoroughly explains the return values for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, verdict, theoretical_sum, capture_ratio, thin_legs, forced_directional_risk). It covers parameter behavior, return fields, and risks (partial fills, directional exposure), making the tool understandable and usable.

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. However, the description adds significant semantic value beyond schema: it explains the difference between single-market and basket modes for each parameter, defines side options per mode, and clarifies the different interpretations of size_usd (spend vs target proceeds for single-market; settlement notional for basket). This justifies a 5.

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'. It explicitly details two distinct modes (single-market and basket) and distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edges by positioning it as a pre-trade risk 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?

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains the consequences of not using it (partial fills converting arb into directional position) and implies when it's not needed (small trades).

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) are complemented by detailed behavioral context: explanation of signal validity, safety fields like compatibility_warning (two cases), temporal_alignment, and skipped counters. 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 thorough but slightly verbose. It uses clear sectioning (two modes, response fields, safety fields) and front-loads the core purpose. Every sentence adds information, but some redundancy (e.g., repeating 'pre-mapped ≠ tradeable') could be trimmed.

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

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

Given the tool's complexity (3 optional parameters, no output schema), the description fully explains what the response contains (leg prices, top spreads, safety fields, counters) and how to interpret results. Edge cases like temporal misalignment and skipped comparisons are explicitly covered.

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 value by listing the 10 topic shortcuts, explaining how explicit parameters override mapped defaults, and providing example invocations. This clarifies usage beyond the schema's basic type/description.

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

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

The description explicitly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question, distinguishing it from siblings like polymarket_arbitrage (single-venue) and polymarket_edges (Polymarket-specific). It clearly defines two modes with concrete examples.

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

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

The description explains when to use topic shortcuts versus explicit pairings, provides example parameters, and warns that pre-mapped topics often yield compatibility warnings. However, it does not explicitly state when to prefer alternative tools like polymarket_arbitrage for same-venue analysis.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context beyond annotations: scoping (anonymous IP, BYO key hash, or account ID) and pairing with related tools. This provides useful insight into data isolation and lifecycle 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 extremely concise, packed into two sentences with no wasted words. It front-loads the core functionality and efficiently conveys additional context, examples, and usage pairing.

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 retrieval tool with one optional parameter, the description is complete. The schema and annotations cover the structural and safety aspects, and the description adds scoping, usage examples, and pairing with sibling tools. No output schema is needed for this tool.

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

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

The schema covers 100% of parameters (one optional 'key' parameter with description). The description adds meaning by explaining the effect of omitting the parameter (list all keys) and providing examples of what keys might represent (ticker, address, notes). This enriches the semantic understanding beyond the schema.

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

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

The description clearly states the tool's purpose: retrieving a value saved via 'remember' or listing all saved keys when the key argument is omitted. It specifies the verb (retrieve/list) and resource (saved values/keys), and distinguishes from sibling tools by naming 'remember' and 'forget'.

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

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

The description explains when to use this tool: to look up context the agent stored earlier, with concrete examples (target ticker, address, research notes). It implies when not to use (avoid re-deriving from scratch) but does not provide explicit exclusions or alternatives. The pairing with 'remember' and 'forget' 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?

Describes mark_read state mutation affecting subsequent calls, adding behavioral context beyond annotations. However, annotations declare readOnlyHint:true, which contradicts the described mutation, reducing trust.

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

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

Single paragraph with 4 concise sentences. Front-loads purpose, each sentence adds value (filters, fields, mark_read effect, alternative access). 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?

Describes return structure (source, citation_uri, raw payload) and polling behavior. Lacks mention of ordering beyond 'most recent' and no output schema, but sufficient for a retrieval tool. Provides alternative script access.

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 meaning: explains mark_read and unread_only effects, since expects ISO timestamp, type filters subscription type. Provides 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?

Clearly states 'Pull fired events from your subscription feed' and specifies return fields (source, citation_uri, raw payload). Distinguishes from siblings by noting alternative GET endpoint for scripts/dashboards, implying this is for interactive MCP use.

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

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

Explains filtering by type and since, polling suitability, and mark_read behavior. Briefly mentions alternative access. Missing explicit when-not-to-use compared to siblings, but usage is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: fan-out to multiple sources, fallback logic (GDELT→GNews), soft-fail for USPTO, accepted date formats, and return structure (changes grouped by source, total_changes, citation URIs). No contradictions.

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

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

The description is front-loaded with example queries and contains valuable information, but it is somewhat lengthy. However, every sentence serves a purpose, and the structure is logical. Could be slightly more concise without losing meaning.

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

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

The description fully explains the return structure (changes[] grouped by source, total_changes count, citation URIs), covers limitations (USPTO soft-fail), and provides usage context. Given the tool's complexity with multiple sources and no output schema, the description is exceptionally complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema: examples for 'since' ("7d", "30d", "3m", "1y"), guidance to use '30d' or '1m', and clarification that 'value' accepts ticker or CIK with examples. This elevates the score to 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 with example queries like 'What's new with X' and lists the data sources (SEC EDGAR, GDELT→GNews, USPTO). It explicitly distinguishes from sibling 'entity_profile', saying to use that for static profiles.

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

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

The description provides explicit guidance on when to use this tool ('change feed for a company in the last N days/weeks/months') and when not to ('Use entity_profile instead when you want the static profile'). It also gives preferred shorthand values ('Use "30d" or "1m" for typical monitoring').

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

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

Adds retention details (24h anonymous, persistent for authenticated) and scope (by identifier) beyond annotations. Annotations already indicate idempotent, but description provides practical behavior.

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 purpose, each sentence adds value. No redundancy, 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?

Tool is simple with two required params and no output schema. Description covers storage behavior, retention, and pairing with siblings, 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 covers both parameters with descriptions (100% coverage). Description adds usage examples but doesn't significantly extend beyond schema. Baseline 3 is appropriate.

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

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

Description clearly states the tool saves data for later reuse, specifies key-value storage, and distinguishes from sibling tools (recall, forget). Verb 'Save' and resource 'memory' are 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?

Explicitly says when to use ('discover something worth carrying forward') and pairs with recall/forget. Lacks explicit '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 already indicate idempotent, readOnly, openWorld, and non-destructive. The description adds that the tool cascades through multiple lookup endpoints, replacing 2-3 manual lookups, and details the return format (ticker, CIK, citation URIs for company; RxCUI, etc. for drug), providing rich behavioral context beyond the annotations.

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

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

The description is somewhat verbose with repeated examples for both entity types. While front-loaded with query examples, it could be more concise. Every sentence is valuable but some redundancy exists.

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

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

Given no output schema, the description fully explains return values for both entity types, including citation URIs and internal cascading behavior. For a 2-parameter lookup tool with 100% schema coverage, the description is complete enough for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the entity types, input formats (e.g., ticker, CIK, name for company), and auto-disambiguation, going beyond the schema's simple 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 resolves names to canonical IDs with specific examples and supported types (company, drug). It distinguishes the purpose from siblings like compare_entities or entity_profile, but does not explicitly differentiate.

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 FIRST whenever you have a name but need an ID', providing strong when-to-use guidance. It lacks when-not-to-use or alternative suggestions, but the context of being a first step 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 indicate readOnly, openWorld, idempotent, non-destructive. Description adds that it internally calls 'ai_visibility_check' per entity and returns a ranked list with score, confidence, signal density. 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 concise, front-loads the key purpose, and each sentence adds value without redundancy.

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

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

Despite no output schema, the description explains the return format (ranked list with score, confidence, signal density) and covers all relevant behavioral aspects for a comparison tool.

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

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

Schema coverage is 100% with descriptions. The description adds that the first entity is treated as 'subject' for narrative, and explains how 'models' and '_apiKey' interact. Enhances schema meaning.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each with 'ai_visibility_check', ranks by score, and identifies most/least recognized. This is specific and distinct from siblings like 'ai_visibility_check' (single entity).

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 suggests use for competitive AI-marketing audits with an example question. It does not directly state when not to use or alternatives, but the sibling list provides context for 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?

Discloses partial failure behavior ('bundlephobia's first measurement... can take 5-30s; sources_failed will list it'), return structure (summary block, advisories, version list), and ecosystem limitation. This goes well beyond the annotations which only mark it as readOnly.

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?

While lengthy, every sentence adds value. The description is front-loaded with the core purpose and then details return/behavior. Could be slightly tighter but far from verbose.

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

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

For a composite tool with no output schema, the description fully covers return fields (summary, advisories, versions), error handling, and ecosystem scope. The agent has all necessary context to invoke 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 coverage is 100%, so the description adds only a minor detail: scoped packages are accepted. Baseline 3 is appropriate; no further parameter insight needed.

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 is a composite check for npm packages combining deps.dev and bundlephobia. The description 'should I add this npm package' makes the purpose immediately understandable and distinguishes it from siblings focused on other ecosystems (e.g., PyPI, Maven).

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: when an agent asks about 'is X safe / popular / small' or 'what does adding lodash cost me'. It also gives clear alternatives: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', preventing misuse.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds technical details: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation. No contradictions with annotations.

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

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

Concise yet comprehensive: first sentence states purpose, followed by usage guidance, pairing with sibling, and technical specifics. Every sentence adds value 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 explains the return format (passages with offsets and similarity scores) and the 200K char limitation. It also contextualizes the tool within a workflow (fetch with gateway, ground over passages). This is highly complete for a search tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the text parameter as the fetched record, providing query examples, and noting the limit range. However, the schema already describes parameters well, so the added value is modest.

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 does semantic search inside a fetched record, with specific verb ('search inside') and resource ('a source'). It distinguishes from sibling tools like ask_pipeworx_grounded by explaining its complementary role.

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

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

Explicitly tells when to use ('when the record is too big to cram into the prompt') and how it pairs with ask_pipeworx_grounded, giving clear alternatives and 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?

The description adds significant behavioral context beyond annotations: it details OAuth requirement, delivery channel limitations (SMS cap, webhook auto-disable), and that the webhook secret is returned only once. It also implies idempotency by stating it returns an ID, consistent with the idempotentHint annotation.

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

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

The description is detailed but well-organized, starting with the main purpose before diving into specifics. Every sentence adds necessary information, though it could be slightly more 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 (multiple types, nested params, delivery channels), the description covers all major aspects. It mentions the return value (subscription ID). Although no output schema exists, the description suffices for an agent to understand and invoke the tool.

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

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

Schema coverage is 100%, so the description adds value by providing concrete examples for each subscription type's params and explaining delivery options. It goes beyond mere schema descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns the subscription ID. It lists supported subscription types with examples, distinguishing it from sibling tools like list_subscriptions or 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?

The description provides usage conditions (requires Pipeworx OAuth account) and explains when to use each subscription type with specific examples. However, it lacks explicit guidance on when not to use the tool or 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, and destructiveHint=false, so the tool's safety profile is clear. The description adds behavioral context: it returns category-bucketed example questions with exact tool+argument shapes, and calling with no arguments gives a full spread while passing a topic focuses. 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 common user queries and then explains the output and listing of topics. It is relatively long but every sentence provides value. A slight reduction in length could be possible, but it's well-organized and easy to parse.

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

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

Given the tool has a simple input schema (one optional parameter) and no output schema, the description fully covers behavior: return type (category-bucketed examples with tool+argument shapes), parameter behavior (omit for full spread, pass topic to focus), and its role in onboarding. The completeness is excellent 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% for the single parameter 'topic'. The description goes beyond the schema by listing example values ('finance', 'pharma', etc.) and explaining that omitting the parameter returns a cross-category spread. This adds meaningful usage context.

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

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

The description clearly states the tool is an onboarding entry point, answering queries like 'what can I ask?' and 'get started'. It distinguishes itself from siblings by advising 'use this FIRST when you do not yet know what Pipeworx can do for you'. The verb 'suggest' is appropriate, and the resource (example questions from a tool catalog) is well-defined.

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

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

The description explicitly says when to use this tool: when the agent just connected or when unsure what to ask. It also explains how to customize with the topic parameter. However, it does not explicitly state when not to use it (e.g., after onboarding), though the phrase 'use this FIRST' implies a one-time introductory role.

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 ownership enforcement and deactivation behavior, aligning with annotations (readOnlyHint false, destructiveHint false, idempotentHint true). It adds detail beyond annotations about the effect on historical data.

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

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

Two sentences, front-loaded with core action, no wasted words. Every sentence adds value.

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

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

Given the simple input and annotations, the description covers ownership, deactivation, and relation to 'recent_alerts.' It lacks return value details, but for a cancellation tool, it is mostly 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 the schema already documents the 'id' parameter. The description only says 'by id,' adding no new meaning beyond the schema's details.

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

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

The description clearly states the tool cancels a subscription by ID, specifying the resource (subscription) and action (cancel/unsubscribe). It distinguishes from sibling tools 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 mentions ownership enforcement and that the row is deactivated not deleted, providing context. However, it does not explicitly state when not to use this tool or mention alternatives, which would improve 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 indicate read-only, idempotent, non-destructive behavior. Description adds detailed return values (verdict, structured form, actual value with citation, percent delta) and notes it replaces 4-6 calls, providing 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?

Front-loaded with key use cases and examples. Slightly verbose but 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?

Single parameter is fully described with examples. Return values are enumerated. No output schema but description covers what to expect. Complete for tool 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 covers parameter definition (100% coverage). Description adds concrete examples and clarifies the natural-language nature, going beyond schema to aid 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?

Description explicitly states the tool validates natural-language claims against authoritative sources, specifies domain (company-financial claims via SEC EDGAR + XBRL), and distinguishes from siblings by noting it replaces multiple sequential calls.

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

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

Clear guidance on when to use ('whenever the agent needs to check factual correctness') with domain restriction. Lacks explicit when-not-to-use but context implies alternatives exist for other claim types.

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