Twelvedata

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

Annotations already indicate readOnlyHint, idempotentHint, openWorldHint. The description adds value by detailing the default model (Workers AI, free), the need for an API key to probe Anthropic, and the cost implication (BYO key). It also outlines the return format (per-model fields + combined view). No contradictions with annotations.

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

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

Three sentences efficiently cover purpose, default behavior, cost model, return format, and use cases. No redundant information. Front-loaded with the main action and outcome.

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 sufficiently details the return structure (per-model score, confidence, signals, raw_response + combined view). Annotations cover safety. Parameter coverage is complete. Use cases and context are provided, making the tool self-contained for an agent.

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

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

Input schema covers all four parameters with descriptions (100% coverage). The description enhances understanding by noting the default model for 'models', the API key prefix 'sk-ant-...' for '_apiKey', and the disambiguation role of 'context'. This raises the baseline from 3 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 probes LLMs for AI visibility and scores it on a 0-100 scale. It specifies the resource (business/brand/product/topic) and outcome (visibility score per model). This distinguishes it from sibling tools like deep_research or scan_competitor_ai_presence.

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 lists concrete use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. While it doesn't explicitly state when not to use it or suggest alternatives, the context and sibling tool list imply it's for visibility audits rather than general Q&A.

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

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

Annotations already cover readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: routing to 5,529 tools, returning pipeworx:// citation URIs, being the default entry point, and working on every tier with one call. It doesn't fully address potential latency or failure modes, but the added context goes beyond the annotation baseline.

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 and front-loaded with the 'PREFER OVER WEB SEARCH' callout. Lists and examples earn their place, though some redundancy exists (e.g., the broad tail 'or anything requiring...'), preventing a perfect score.

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 highly complex routing tool with no output schema, the description is remarkably complete: it covers return format (structured answer with citations), usage heuristics, alternatives, and examples. It leaves no major gaps for an agent to select and invoke this tool appropriately.

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

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

Schema coverage is 100% and already documents the 'question' parameter plus all aliases. The description itself does not add parameter syntax or format details beyond the examples embedded in the schema, so the baseline of 3 applies.

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

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

The description clearly states the tool routes questions to thousands of tools and returns structured answers with citations. It explicitly lists domains (SEC filings, FDA data, etc.) and provides examples, distinguishing itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

It explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', with concrete when-to-step-up guidance for alternatives (ask_pipeworx_grounded and deep_research). It also gives user-phrase triggers and six concrete example queries, making usage exceptionally clear.

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

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

Beyond the readOnly and idempotent annotations, the description discloses important behavioral traits: live candidate routing may alter behavior, currently no candidate is active making it identical to stable, and it falls back to nothing because it is a full working router. This adds significant transparency about the experimental nature.

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

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

The description is three sentences and front-loaded with the beta status and core fact. Each sentence adds value (beta nature, current state, usage instruction). Slightly verbose with '(same 5,529 tools, same arguments, same response shape)' but acceptable for the needed transparency.

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

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

The description covers the essential context: what the tool does, its experimental status, exact current behavior, how to use it, and the lack of fallback. With rich annotations and full schema coverage, this is complete for an agent to reliably select 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 description coverage is 100%, with each parameter having a description, so the baseline is 3. The description adds little beyond stating 'same arguments' as ask_pipeworx, which is redundant given the schema already documents the aliases and question field. No extra semantic value.

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

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

The description clearly states this is a beta version of ask_pipeworx, a universal router with the same 5,529 tools and response shape. It immediately distinguishes itself from the stable sibling by referencing candidate routing improvements, satisfying the verb+resource+scope criterion.

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

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

It explicitly tells the agent when to use this betaversion ('when you want the newest routing') and implies the alternative is the stable ask_pipeworx. It also notes that results are compared against the stable router, providing clear usage context and exclusions.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds valuable behavioral context: returns a structured result with evidence and refusal_reason, uses ONLY tool content, and enumerates specific refusal reasons. 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?

Every sentence earns its place: purpose, mechanism, return format, usage guidance, and cost trade-off. The description is front-loaded with the core purpose and uses structured lists, making it dense yet readable 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 there is no output schema, the description fully describes return fields, refusal reasons, and success/failure behavior. It also covers when to use vs alternatives and cost implications. For a tool with this complexity, the description is remarkably 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%, with all parameters documented as aliases for 'question'. The description adds no additional parameter-level detail, but the schema already fully explains the required input, so baseline 3 is appropriate.

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

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

The description clearly states this is a hallucination-resistant answer mode for high-stakes reads, distinguishing it from the sibling ask_pipeworx by emphasizing extraction using only tool results and explicit refusals. The verb 'extracts' and resource 'answer from tool results' are specific and unambiguous.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on' and when not: 'prefer ask_pipeworx for casual lookups.' It also names the alternative tool and explains the cost trade-off (one extra LLM call).

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description massively expands on this with fan-out examples, resolver contract (confidence levels, alternatives, suggestions), parent event extraction, news fallback logic, safety guards for low-confidence and closed markets, and resolution-rule risk (cancellation_rule). 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 long but well-structured, starting with the core purpose and progressively adding detail. Each section (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) earns its place given the tool's complexity. Every sentence provides value, though the length might slightly challenge an agent scanning quickly. Still, front-loaded with essential info.

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

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

Given no output schema, the description must explain return values, which it does thoroughly: response shapes for result.market, result.analysis, result.evidence; resolver contract; parent event extractor; news fields safety; and resolution-rule risk. It covers edge cases like low-confidence matches, closed markets, wide spreads, and cancellation rules. Complete for a complex data-fetching 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% for the 3 parameters (market, depth, include_raw). The description adds substantial meaning: explains the four formats for market (slug, URL, question text), clarifies depth enum values with their implications (quick vs thorough), and describes include_raw effect on response size. Examples in schema and description enrich 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 starts with a clear verb+resource statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and what the tool does (resolves, classifies, fans out to data packs). This distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges, which serve different purposes.

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

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

Explicit usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' The description also details when the tool short-circuits (low confidence, closed markets, wide spreads) and advises checking market_match_confidence before trusting analysis. This provides clear context for when to use and what to expect.

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

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

Annotations already mark the tool as read-only and idempotent, but the description adds critical behavioral details: it pulls latest 10-K financials from SEC EDGAR/XBRL for companies (including off-calendar fiscal year handling) and FAERS/FDA data for drugs. It also describes result sorting and citation URIs, going well 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 a single dense paragraph, information-rich with no wasted words. It front-loads typical user queries and covers all key aspects. However, it could be slightly more structured (e.g., breaking company vs. drug into separate lines) for easier scanning, but overall it's efficient and concise.

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

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

For a tool with no output schema, the description adequately explains return format (paired data + citation URIs) and sorting order. It covers data sources and entity types thoroughly. Minor gaps include error handling or limitations (e.g., only latest fiscal year), but given the complexity, it's sufficiently complete.

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

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

Input schema coverage is 100% with descriptions for both parameters. The description adds value by providing concrete examples ('AAPL', 'MSFT' for companies; 'ozempic', 'mounjaro' for drugs) and clarifying the format (tickers/CIKs vs. names) and constraints (2–5 items). This enriches the schema's bare definitions.

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

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

The description opens with user-language examples like 'Compare X and Y' and 'head to head', immediately clarifying the tool's purpose: side-by-side comparison of 2–5 companies or drugs. It distinguishes between entity types and specifies the data pulled for each, making the purpose unmistakable and differentiated from single-entity siblings.

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

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

The description explicitly instructs to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. It also implies when not to use (single entity lookups) by contrasting with sequential lookups, and the sibling list confirms alternatives like 'profile' and 'quote' exist.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, making safety clear. The description adds useful context about being a 'reference list' with 'exchange metadata' and 'all supported' symbols. It does not mention pagination or rate limits, but the core behavioral expectation is transparent.

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 that are front-loaded and efficient. The first sentence defines the tool's purpose and source, the second provides usage guidance. No redundant or filler content.

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

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

Given the tool's simplicity (2 optional parameters, high schema coverage, output schema exists), the description fully equips the agent to use it correctly. It explains why to use it (discovery/validation before price queries) and what it returns (symbols with exchange metadata).

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 well-described parameters (e.g., 'Optional pair filter (e.g. "BTC/USD")'). The tool description does not add any additional parameter information beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool provides a 'reference list of all supported cryptocurrency symbols with exchange metadata' using the verb 'discover or validate'. It distinguishes itself from sibling tools like 'stocks' and 'forex_pairs' by targeting crypto tickers specifically.

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 to discover or validate crypto tickers before querying price endpoints', providing clear context. However, it does not mention when not to use it or list alternative tools, so it falls short of a 5.

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, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds 'real-time' and 'current exchange rate' context, but does not disclose any additional behavioral traits beyond what annotations cover. With the annotations handling safety, the description adds marginal value.

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

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

The description is a single, front-loaded sentence that covers the core purpose without unnecessary elaboration. It is concise yet informative, though it could be slightly more structured by separating input details.

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

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

With an output schema present, the description does not need to detail return values. It covers the primary use case and mentions real-time conversion. It does not explicitly address batch processing (comma-separated symbols) which is in the schema, but overall it is sufficiently complete given the richness of structured fields.

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

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

Schema coverage is 100%, so the schema already documents all four parameters with descriptions and examples. The description does not add new semantic meaning beyond the schema; it only reiterates example symbols. Baseline 3 is appropriate.

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

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

The description clearly states it performs real-time currency conversion using Twelve Data, specifies the required inputs (forex pair symbol and amount) and the output (converted value at current exchange rate). This is a specific verb+resource combination that distinguishes it from sibling tools like exchange_rate or forex_pairs.

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 by specifying inputs ('pass a forex pair symbol...'), but it does not provide explicit guidance on when to use this tool versus alternatives like exchange_rate or forex_pairs, nor does it mention when not to use it.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses critical behaviors: returns gaps[] for unanswered facets ('never invented'), uses parallel execution of 5,529 tools, requires an account, and has latency of 15-60s (up to ~90s for thorough). It also explains citation_uri resolvability and semantic excerpting, adding substantial context not present in the structured metadata.

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

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

The description is a single dense paragraph packed with high-signal information, but it is somewhat sprawling with multiple parentheticals and repeats schema-level depth details. Every sentence contributes, but a clearer structure (e.g., separating 'when to use' from behavioral details) would improve scannability. It earns a 4 because it is information-dense without being terse to the point of omission.

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

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

For a tool with no output schema, the description thoroughly explains the return format (findings packet, gaps[], contradictions[], hop, citation_uri), access prerequisites, latency expectations, and depth variations. It covers essentially every operational aspect an agent needs to invoke the tool correctly and interpret results, making it highly complete.

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

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

The schema already provides 100% coverage with detailed descriptions for both parameters. The description adds value by tying depth:'thorough' to a paid plan and noting that the question param should be broad/multi-part ('decomposition is the point'). While much of the depth behavior is redundant with the schema, the paid-plan caveat is a useful supplement.

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 function: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call' and distinguishes it from open-web search. It specifies the mechanism (decomposes question into facets, routes to tools in parallel) and the return format (findings packet), making the purpose unambiguous.

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

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

The description explicitly tells when to use this tool versus alternatives: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx'. It also covers access conditions ('ACCOUNT REQUIRED', paid plan for thorough), leaving no ambiguity about when this tool is appropriate.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by detailing output: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' 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 efficiently structured: first sentence states purpose, second gives examples, third explains output format, and fourth provides usage guidance. It is slightly long but every sentence adds value and is front-loaded with key information.

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

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

Despite no output schema, the description fully explains the return format (top-N tools with full schemas and examples). Given the tool's complexity (6 parameters, discovery use case) and rich annotations, the description is sufficiently complete for an agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for all 6 parameters. The description adds context that 'query' is a natural language description, but this is already implied in schema descriptions. With high coverage, baseline is 3; the description provides minimal additional 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's purpose: 'Find tools by describing the data or task.' It provides numerous domain examples and explains that it returns top-N relevant tools with full schemas, ready to call. This distinguishes it from sibling tools that provide specific data (e.g., 'stocks', 'price') rather than discovering tools.

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

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

The description advises: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear guidance on when to use it for browsing/discovery. It doesn't explicitly say when not to use, but the sibling list implies alternatives for specific data needs.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that data is historical and from Twelve Data, but doesn't discuss behavior on missing symbols or rate limits. The added value is moderate.

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 source and resource, no fluff. Every sentence adds value: first identifies tool, second states purpose.

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

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

Output schema exists (not shown but context confirms), so description need not detail returns. It does summarize key return fields. It covers the main purpose and constraints (Twelve Data coverage). Lacks mention of pagination or limits, but acceptable for this tool's simplicity.

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 3. The description does not add meaning to parameters; it only mentions return fields (ex-date, amount, frequency). No additional parameter 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?

The description uses specific verb 'historical dividends' for a 'stock/ETF symbol', lists key fields (ex-date, amount, frequency), and states use cases, clearly distinguishing from sibling tools like earnings or splits.

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

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

Explicitly states 'Use for income analysis and dividend-capture strategies', providing clear context. Could be improved by explicitly mentioning when not to use or naming alternatives, but the implied usage is clear given the sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds that it returns historical and upcoming earnings, but no additional behavioral traits (e.g., rate limits, data freshness) beyond what annotations provide.

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

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

The description is a single, concise sentence with no unnecessary words. It efficiently conveys the tool's purpose and data content.

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

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

Given the presence of an output schema and full annotation coverage, the description sufficiently explains the tool's functionality. No critical information is missing for an AI agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the description adds no new parameter meaning beyond listing returned fields. Baseline of 3 applies as the description does not enhance understanding of parameters.

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

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

The description clearly states the tool retrieves earnings history and upcoming dates for a stock symbol, listing specific data fields (EPS estimate, actual, surprise, report date). It effectively distinguishes itself from siblings like 'earnings_calendar' by focusing on per-symbol quarterly data.

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

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

The description implies usage for earnings data per symbol but does not explicitly state when to use this tool versus alternatives like 'earnings_calendar' or 'dividends'. No when-not or exclusion criteria are provided.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds that it returns symbol, date, EPS estimate, and time of day, which provides behavioral context beyond annotations but does not disclose any restrictions or side effects.

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

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

The description is two concise sentences with no wasted words. It front-loads the purpose and then lists return fields efficiently.

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 output schema exists and annotations cover safety and open-world behavior, the description sufficiently explains the tool's scope (all symbols, upcoming and recent) and return values. It is complete for a simple calendar tool with optional parameters.

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

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

Both parameters (start_date, end_date) have descriptions in the input schema, achieving 100% coverage. The description does not add extra meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool provides a broad earnings calendar with upcoming and recent announcements across all covered symbols, and specifies the return fields (symbol, date, EPS estimate, time of day). This distinguishes it from sibling tools like 'earnings' by emphasizing broad coverage.

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

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

No guidance is given on when to use this tool versus alternatives (e.g., 'earnings' for specific symbols). The description lacks explicit context about appropriate use cases 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=true, idempotentHint=true, openWorldHint=true, destructiveHint=false. Description adds useful context: it fans out across multiple sources, returns specific fields (e.g., 'cik + company_name', 'recent_filings (up to 5 with ... URIs)'), and mentions the USPTO PatentsView API sunset May 2025 with soft-fail behavior. 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 fairly long but well-structured, starting with example queries, then stating the core purpose, and listing return components. While every sentence adds value, it could be slightly more concise 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?

The description covers the essential aspects: what the tool does, when to use it, what it returns (including URIs and sorting), and known limitations (patent API sunset, name not supported). No output schema exists, but the description lists return components adequately for an agent to decide.

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

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

Schema coverage is 100% with descriptions for both parameters. The description reinforces that 'value' accepts ticker or zero-padded CIK and explicitly states names are not supported, adding practical guidance beyond the schema.

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

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

Description starts with clear example queries and states 'full cross-source profile of a US public company in ONE parallel call'. It specifies the exact data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and what it returns, making it distinct from siblings like 'profile' or 'deep_research'.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and advises to use 'resolve_entity first if you only have a name'. This gives direct guidance on when to use this tool and when to use an alternative.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds return value info (price, volume, date) and source (Twelve Data), but doesn't disclose additional behavioral traits like rate limits or data freshness. No contradiction with annotations.

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

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

Two sentences, front-loaded with main purpose. Every sentence adds value with no fluff.

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

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

Description covers return value fields clearly. Output schema exists, so return format is documented. Could mention batch capability or how to use comma-separated symbols, but schema covers that. Adequate for a simple query 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 descriptions for both parameters (symbol with examples, exchange optional). Description does not add new parameter details beyond schema, so baseline score of 3 applies.

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

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

Description clearly states it returns end-of-day closing quote for a symbol, listing specific fields (price, volume, date). Distinguishes from intraday data, making purpose precise.

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

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

Explicitly recommends use for daily settlement prices and contrasts with intraday data, guiding when to use. Does not explicitly list alternatives, but context and sibling tools imply when not to use.

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

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

Annotations already cover readOnly, idempotent, openWorld, and non-destructive nature. Description adds that it returns 'exchange and country metadata' but doesn't go beyond annotations significantly. No contradiction.

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

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

Two concise sentences that are front-loaded with the core purpose. Every word adds value, no fluff.

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

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

Given a single optional parameter, comprehensive annotations, and an output schema, the description sufficiently conveys the tool's role and usage. No additional context is necessary.

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

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

Schema coverage is 100% with a clear description for the optional 'symbol' parameter. The tool description does not add any additional parameter details beyond what the schema already provides.

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

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

Description clearly states the tool returns a reference list of valid ETF symbols with metadata, and positions it as a discovery/validation step before price queries. Distinguishes from siblings like 'stocks' and 'cryptocurrencies' by focusing on ETFs.

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: 'before querying price endpoints' for discovering or validating tickers. Does not explicitly mention when not to use, but the context implies it's for reference only.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) already convey safety and idempotency. The description adds that the tool returns 'rate, timestamp, and pair identifiers', but does not fully align with the schema's broader asset scope, reducing transparency.

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

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

Single sentence, front-loaded with essential information. Every word earns its place 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 having an output schema and annotations, the description incorrectly restricts the tool to 'forex' while the schema supports stocks, crypto, indices, and ETFs. This incomplete and contradictory context undermines completeness for an agent.

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 detailed parameter descriptions (e.g., symbol supports multiple asset types and batch queries). The description only mentions symbol, dp, and timezone briefly, adding no significant meaning beyond the schema.

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

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

Description clearly states the tool provides live forex exchange rate for a currency pair symbol, e.g., 'EUR/USD'. It uses a specific verb ('returns') and resource ('exchange rate'). While sibling tools like 'currency_conversion' and 'forex_pairs' exist, the focus on live forex rate distinguishes it, though not explicitly.

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

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

No guidance on when to use this tool versus alternatives. The description says 'live forex exchange rate' but the 'symbol' parameter includes stocks, crypto, etc., creating a mismatch that could mislead agents about appropriate use cases.

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

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

Annotations already cover read-only, idempotent, non-destructive nature. Description adds value by specifying it's a 'reference list' from 'Twelve Data' and intended for enumeration/validation. No contradiction.

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

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

Two concise sentences with no wasted words. Key information is 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?

With an output schema present and only optional parameters, description sufficiently covers purpose, usage context, and sibling tool linkage. No gaps.

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

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

Schema coverage is 100% with clear parameter descriptions. Description only reiterates the filter pattern without adding new meaning. Baseline 3 is appropriate.

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

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

Uses specific verbs 'enumerate or validate' on a clear resource 'forex currency pairs'. Distinguishes from siblings by naming 'exchange_rate' and 'time_series' as downstream 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?

States explicitly to use 'before querying exchange_rate or time_series', providing clear context. Does not include explicit exclusions but the usage scenario is well-defined.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds context about what gets destroyed (stored memory by key) without contradicting annotations. No additional details on permissions or side effects, but sufficient for this simple operation.

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

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

Two succinct sentences that front-load the action and purpose, with no extraneous information. Every sentence earns its place.

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

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

For a one-parameter deletion tool with no output schema, the description adequately covers the function. Could mention whether confirmation is returned, but overall complete given simplicity.

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 single parameter 'key' is documented with description 'Memory key to delete'. The tool description does not add further meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

Description clearly states 'Delete a previously stored memory by key' using a specific verb and resource, and distinguishes from sibling tools 'remember' and 'recall' by mentioning pairing.

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 context is stale, the task is done, or you want to clear sensitive data.' Also references related tools for 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 behavioral context beyond annotations: it fetches the page, extracts title/description/key links, and emits markdown. Annotations already signal safe, idempotent, non-destructive behavior; description confirms and details the process.

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 compact sentences: purpose, process, use cases. No extraneous content, well front-loaded.

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

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

Given only 2 parameters and no output schema, the description fully explains input defaults and output format ('single text blob'). 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%, but description adds value by specifying defaults (25) and maximum (50) for max_links, and an example for url. This aids correct invocation beyond bare 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 generates a production-ready llms.txt file for any URL, using a specific verb and resource. It distinguishes from sibling tools, none of which are similar.

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 lists three concrete use cases (client site, own project, competitor audit) but does not explicitly mention when not to use 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 idempotent, read-only, non-destructive, and open-world behaviors. The description adds that it's a reference list with exchange metadata, which is useful but not critical beyond annotations. No contradictions.

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

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

Two concise sentences: first defines the tool's output, second states its recommended use. No superfluous information, perfectly 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 reference tool with full schema coverage, output schema, and robust annotations, the description adequately covers purpose and usage. No further details needed.

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

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

Input schema coverage is 100%, so baseline is 3. The description does not add additional meaning about parameter usage beyond what the schema already provides (e.g., optional filters). The examples in schema suffice.

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

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

The description clearly states the tool is a reference list of market index symbols with exchange metadata, giving concrete examples (SPX, DJI). It distinguishes itself from siblings like time_series by specifying its use for discovery/validation before querying that sibling.

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

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

Explicitly advises to use this tool to discover or validate index tickers before querying time_series, providing clear contextual guidance. It implies not to use it for direct data retrieval, aligning with its reference nature.

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 signal read-only, idempotent, and non-destructive behavior. The description adds value by listing exactly which fields are returned and mentioning the optional 'include_inactive' parameter, which is beyond the annotation scope.

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

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

Two well-structured sentences: the first states purpose and return fields, the second gives actionable usage guidance. No unnecessary words, and critical information is 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?

Despite lacking an output schema, the description explicitly lists return fields. Combined with thorough annotations, this provides complete context for an agent to understand behavior and output.

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

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

The input schema has 100% coverage with a clear description for the single parameter. The tool description does not add any additional details about the parameter, so a baseline score of 3 is appropriate.

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

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

The description explicitly states the verb 'List', the resource 'subscriptions', and elaborates on the returned fields (id, type, params, etc.), leaving no ambiguity about the tool's function.

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 directly tells the agent when to use this tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and helps differentiate from siblings like subscribe/unsubscribe.

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

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

Annotations are all false/neutral, so the description carries the burden. It discloses that filing returns a claim_token, that passing it back later retrieves status/changes, that it is rate-limited to 5 per identifier per day, and that it is free and doesn't count against the tool-call quota. This goes well beyond what annotations provide.

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

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

Though a single dense paragraph, every sentence adds necessary information: purpose, usage, exclusion, token flow, rate limit, and roadmap impact. Front-loaded with the core action; no fluff or redundancy. Length is justified by the tool's many behavioral nuances.

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, triggers, exclusions, claim_token flow for later retrieval, team review cadence, daily rate limit, and quota exemption. Given the absence of an output schema, the description adequately explains return value semantics and subsequent usage. Nothing essential is missing.

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 detailed per-parameter descriptions (including enum meanings). The description adds extra usage guidance not in the schema: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt' and 'Not sure? Pipeworx tool names are the ones this connection lists.' This improves correct parameter population beyond 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 first sentence 'Tell the Pipeworx team something is broken, missing, or needs to exist' clearly states the tool's purpose. The description enumerates feedback categories (bug, feature/data_gap, praise) and distinguishes it from all sibling tools, which are data/research oriented.

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

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

Explicitly specifies when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' This is model 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?

Beyond annotations (readOnly, idempotent), the description adds caching behavior (5min-1h), data source (CF analytics), and no PII. This is valuable context not captured by structured fields.

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 at 4 sentences, front-loaded with the main purpose, then use cases, then technical details. No wasted words.

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

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

Given no output schema, the description lists the return fields (top tools, top packs, total call volume), which is sufficient for an AI agent. Could be more precise about structure, but adequate.

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

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

The schema already covers the parameter with a description. The description adds semantic nuance about shorter vs longer windows, enhancing meaning beyond the schema. Since schema coverage is 100%, baseline is 3; the extra context earns a 4.

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

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

The description clearly states the tool returns trending tools/packs and call volume, with explicit use cases. It distinguishes itself from siblings by focusing on trending data from other agents.

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

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

The description provides three specific use cases, giving clear context for when to use. However, it does not explicitly discuss when not to use or alternatives.

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

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

The description goes well beyond annotations (readOnlyHint, openWorldHint, idempotentHint) by detailing semantic anchor requirements (≥0.30 Jaccard similarity), partition filtering (placeholders), and fill check logic that rejects non-tradeable opportunities. No contradiction with annotations.

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

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

The description is long but well-structured, with clear sections for different modes and important notes (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It front-loads the main purpose and usage, but some details could be condensed.

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 comprehensively covers inputs, modes, edge cases, and response structure (opportunities[], partition_check, fill_check). It also mentions behavior for edge cases like placeholders and low similarity.

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%, providing baseline. The description adds significant value by explaining the difference between event and topic, giving concrete examples (slugs, seed questions), and describing their effects on scanning and response.

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 using monotonicity violations and partition-sum checks. It distinguishes three usage modes (no args, event, topic) with specific behaviors, making it easy to understand the tool's 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 each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. It explains why cross-event mode catches patterns single-event misses, and even directs to polymarket_fill_risk for custom sizing.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds extensive behavioral context beyond annotations: caching (1h at KV level), model internals (lognormal barrier, GDELT ratio), edge computation (edge_pp_net after slippage), tradeable-edge knobs, and diagnostic output. No contradictions.

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

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

The description is lengthy but well-structured with clear sections (model families, knobs, output format). Every sentence adds necessary detail, and key information is front-loaded with the purpose. Minor redundancy could be trimmed, but overall efficiently communicates complex tool behavior.

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

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

Given the tool's complexity (9 parameters, no output schema, multiple segments), the description is remarkably complete. It explains the three response segments, diagnostic fields fed_candidates and _diagnostics, caching behavior, and how each knob affects results. Without an output schema, the description sufficiently guides users on what to expect.

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

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

Schema coverage is 100% with all 9 parameters described. The description adds value by explaining the purpose and usage context of key parameters (e.g., 'Tradeable-edge filter' for max_spread_pp and min_liquidity, why min_partition_leg_kelly exists), and provides real-world context like Polymarket's zero fees and typical slippage.

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: 'Scan top Polymarkets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb (scan, return) and resource (markets, opportunities), and distinguishes from sibling tools by emphasizing Pipeworx data and model families.

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 'Built for "what should I bet on today"' and explains that agents can discover opportunities without paging hundreds of markets. It gives detailed guidance on when to use each segment and the tradeable-edge knobs, though it does not explicitly state when not to use the tool or compare it to siblings.

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

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

The description fully discloses the tool's behavior beyond annotations: explains response structure (tracked, expired, snapshot_dates), computed fields (trend, decay_pp_per_day), and limits (60-day TTL, decay based on daily closes). No contradictions with annotations.

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

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

The description is front-loaded with purpose and structured into response sections and limits. While it is somewhat verbose, every sentence adds value. Minor redundancy with schema defaults could be trimmed, but overall well-organized.

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 thoroughly explains the return structure, computed fields, and limitations. All aspects of the tool's behavior are covered, making it complete for effective use.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds limited additional meaning beyond defaults and options. Baseline score of 3 is appropriate as the schema already carries the semantic load.

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 a specific question about edge longevity and distinguishes itself from sibling tools like polymarket_edges by focusing on historical trends rather than current edges.

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

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

The description provides clear guidance on when to use the tool: to assess whether an edge is new or old and decaying. It contrasts the trade implications of fresh vs. old edges. While it doesn't explicitly list alternatives, the context is sufficient for correct usage.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds detailed behavior: walks the ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, and for basket: theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk. No contradictions.

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

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

Well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Slightly verbose but every sentence contributes substantial information. Could be marginally shorter but excellent structure.

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 lists all return fields and explains the logic comprehensively. Covers both modes, risks (thin books, partial fills), and directional risk. Complete for a tool of this complexity.

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

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

Schema coverage is 100%, but description adds significant value: explains default side auto logic for basket, size_usd interpretation as settlement notional for basket, and clarifies that market/event determine mode. Goes beyond schema to explain usage and defaults.

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 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It also explicitly tells when to use this tool before other sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Warns against partial basket fills converting arb into unhedged directional position, and explains when each mode applies.

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 goes far beyond annotations: it details safety fields (compatibility_warning, temporal_alignment, skipped types), explains why spreads may be invalid, and describes the output structure. Annotations already indicate readOnly and idempotent, but the description adds rich behavioral context without contradicting them.

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

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

The description is well-structured with headings (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with purpose. Despite length, every sentence adds value, and there is no redundancy or fluff.

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

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

Given no output schema, the description compensates by explaining the response format (leg-by-leg prices, spreads, safety fields). It also covers edge cases (compatibility warnings, temporal misalignment) and provides examples. The tool has only 3 parameters with full schema coverage, so the description is complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the two modes (topic vs explicit tickers), listing the shortcut values, and describing how overrides work. This provides context beyond the schema's type definitions.

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

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

The description explicitly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, which is a specific verb+resource combination. It distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison, and the two modes are clearly delineated.

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?

Guidelines are implicit: the description explains two modes (topic shortcuts vs explicit tickers) and warns that most pre-mapped topics return compatibility warnings. It does not explicitly compare to sibling tools or state when not to use, but it provides context on when spreads are meaningful (e.g., temporal alignment).

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by noting it returns only a single numeric field and is the 'lightest endpoint,' providing performance context beyond what annotations offer.

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?

Extremely concise: two sentences that immediately state the tool's purpose, scope, return format, and performance characteristic. 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 output schema exists and description matches the single numeric field return, it is largely complete. However, the batch capability mismatch limits completeness, as agents might incorrectly assume only single symbols are accepted.

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

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

Input schema has 100% coverage, so baseline is 3. However, the description states 'single symbol' while the schema's symbol parameter explicitly allows comma-separated batch queries (e.g., 'AAPL,MSFT'). This contradiction misrepresents parameter capabilities, reducing clarity.

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 returns the latest trade price for a single symbol across multiple asset types. Highlights it's the 'lightest endpoint' for current-price lookups, distinguishing it from heavier endpoints. However, it does not explicitly differentiate from similar tools like 'quote' or 'stocks'.

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?

Implied usage via 'lightest endpoint for current-price lookups' suggests using when only a price is needed. No explicit when-not or alternative tools mentioned, leaving room for ambiguity among sibling tools.

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

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

Annotations already declare readOnlyHint=true, so safety is clear. Description adds content about returned fields but no additional behavioral traits like rate limits or data freshness.

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 sentence, 20 words, front-loaded with key verb and resource. 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?

Lists returned fields, which suffices given output schema exists. However, fails to mention batch capability (comma-separated symbols) and the discrepancy about symbol types reduces completeness.

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

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

Schema coverage is 100% with clear descriptions for both parameters. Description adds no extra meaning beyond what schema provides; slight inconsistency ('stock symbol' vs broader schema) is minor.

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 retrieves a company profile with specific fields like name, sector, CEO, etc. However, it specifies 'stock symbol' while the schema includes forex, crypto, etc., causing slight ambiguity. It doesn't explicitly differentiate from sibling 'entity_profile'.

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

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

No guidance on when to use this tool versus alternatives like 'entity_profile' or 'stocks'. No when-not-to-use or any context for selection among siblings.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false, so the description adds limited behavioral context beyond listing output fields. No contradictions, but the description could elaborate on data freshness or rate limits.

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

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

Two sentences with no wasted words. Essential information (data source, fields, usage hint) is front-loaded. Efficient 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 output schema exists (not shown), the description sufficiently explains inputs and output fields. It covers the main use case but could mention relationship to sibling tools like 'price' for completeness.

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

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

Schema coverage is 100% with detailed descriptions for all 4 parameters, including examples and constraints. The description does not add extra parameter meaning beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

Description clearly states the tool returns a real-time quote snapshot with specific fields (open, high, low, close, volume, etc.) and suggests use for a full current-day market snapshot. However, it does not explicitly differentiate from sibling tools like 'price' or 'time_series', which may have overlap.

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 a clear when-to-use ('full current-day market snapshot') but lacks explicit when-not-to-use or alternatives. Sibling tools like 'price' or 'eod' exist but are not mentioned, leaving ambiguity about selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds context (scoping by identifier, no side effects) and reinforces the read-only nature.

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 focused sentences with no wasted words. Front-loaded with main action, then usage guidance, then scope and companion tools.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers all essential aspects: what it does, how to use, scope, and related tools.

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

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

Schema coverage is 100% and the description adds meaning: explains that omitting key lists all keys, complementing the schema's optional parameter.

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

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

The description uses specific verbs ('Retrieve', 'list') and clearly identifies the resource (saved values by key), distinguishing it from sibling tools '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?

Explicitly states when to use (look up stored context without re-deriving) and mentions companion tools (remember, forget), but does not explicitly state when not to use.

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

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

Annotations already provide readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavior details: return structure (source, citation_uri, raw payload), mark_read effect on subsequent calls, and the existence of an HTTP endpoint. 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 fluff. The first sentence states the core purpose, followed by return structure, filtering options, and mark_read behavior. The final sentence adds practical usage guidance (polling and HTTP endpoint). Every sentence adds distinct 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?

With no output schema, the description adequately describes return fields. It covers all major use cases (filtering, mark_read, unread only implied), and provides context for polling and alternative access. Given the tool's complexity and annotations, the description is complete enough.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context by explaining the mark_read flag's behavior (flags returned events as read) and mentions filtering by type and since. It does not mention unread_only, but the schema covers it. The additional context raises the score above baseline.

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

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

The description clearly states the tool pulls fired events from the subscription feed, focusing on recent alerts with specific fields (source, citation_uri, raw payload). It distinguishes itself from sibling tools like list_subscriptions and subscribe by being the tool for retrieving actual alert data.

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

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

Provides explicit filtering options (type, since) and explains mark_read behavior for managing read status across calls. Mentions polling and the alternative HTTP endpoint, giving context on when to use the tool vs. the API. Lacks explicit 'when not to use' guidance for sibling tools but is otherwise clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds valuable behavioral context: multi-source aggregation with fallback (GDELT→GNews on rate limit/5xx), USPTO soft-failure, output structure (changes grouped by source + total_changes + URIs). No contradictions.

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

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

Single paragraph is dense but well-structured: starts with usage examples, then sources, parameters, output, and sibling guidance. Every sentence adds value. Slightly long but not 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?

Covers all aspects for a complex tool: purpose, alternatives, parameter details, fallback logic, output format, and limitations. No output schema exists, but description sufficiently explains return structure.

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

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

Schema coverage is 100% but description greatly enriches understanding. Explains `since` format with examples ('7d', '30d', '3m', '1y') and recommends '30d' or '1m' for monitoring. Clarifies `value` accepts ticker or CIK. Connects parameters to tool behavior (e.g., window for EDGAR).

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

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

Description starts with concrete examples ('What's new with X', 'latest on Y') that make the tool's purpose immediately accessible. It clearly states returning a change feed for a company over a recent window and explicitly distinguishes it from the sibling `entity_profile` tool.

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

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

Provides explicit when-to-use guidance: 'Use entity_profile instead when you want the static profile'. Also details what the tool fans out to (SEC EDGAR, GDELT→GNews, USPTO) and fallback behavior, helping the agent decide when to invoke this tool.

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

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

Annotations indicate write (readOnlyHint=false), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false). The description adds context about persistence duration (24h vs persistent), scope by identifier, and pairing with recall/forget. 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 wasted words: purpose, usage, details, pairing. Front-loaded and well-structured.

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

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

For a simple 2-param tool with no output schema, the description covers purpose, usage, persistence, scope, and sibling tools. 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 has 100% description coverage for both parameters (key and value). The description adds usage context but no new technical details about the parameters beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states 'Save data the agent will need to reuse later', specifying a verb and resource. It distinguishes itself from sibling tools 'recall' and 'forget' by explicitly mentioning them as complementary.

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

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

Provides explicit guidance on when to use ('when you discover something worth carrying forward') with concrete examples. Mentions scope and retention differences for authenticated vs anonymous users. Does not state when not to use, but is clear enough for the agent to decide.

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

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

Beyond annotations, the description discloses that unresolved identifiers are explicitly listed under `unresolved`, that LEI/FIGI enrichment degrades gracefully with EDGAR identifiers still returned, and that each call cascades through multiple endpoints. These add significant behavioral context.

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

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

The description is dense but front-loaded with example queries and a clear purpose. It's longer than typical, but every sentence adds substantive detail on behavior and supported types; 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?

The tool is complex with two entity types and multiple identifier sources. The description covers input variants, output identifiers, source labeling, unresolved handling, graceful degradation, and the fact that it replaces multiple lookups—making it complete for inference without an output schema.

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

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

Input schema already describes both parameters with examples. The description adds behavioral output details (e.g., CIK, ticker, LEI, FIGI for company; RxCUI, ingredient, brand for drug) that help the agent know what to expect, but the schema covers the basic meaning fully.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with a specific verb ('resolve') and resource ('entity'). It provides example queries and distinguishes it from siblings by positioning as the 'FIRST' step for name-to-ID 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?

Explicit guidance 'Use FIRST whenever you have a name but need an ID' tells the agent when to invoke. The description also notes it replaces 2-3 manual lookups, implying efficiency benefit. However, it doesn't explicitly mention when not to use 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, idempotentHint, openWorldHint. 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?

Three sentences, each carrying distinct value: purpose, process, use case, and output format. No waste, front-loaded with key action.

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

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

Despite no output schema, description fully explains return structure (ranked list with score, confidence, signal density) and composite nature. Covers all necessary context for selection and use.

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

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

Schema covers 100% of parameters with descriptions. The description adds extra meaning: first entity treated as 'subject' for narrative, context disambiguates common names. This exceeds schema documentation.

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

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

Description clearly states verb 'compare'/'scan' and resource 'AI visibility across multiple entities'. It distinguishes from sibling ai_visibility_check (single entity) by explicitly stating it probes multiple entities and ranks them.

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

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

Description provides clear use case: 'competitive AI-marketing audits' and contrasts with ai_visibility_check by describing the composite operation. It does not explicitly state when not to use, but the context is sufficient for selection.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds critical behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. 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 informative but slightly verbose. It front-loads the main purpose and adds useful detail. Minor redundancy in listing return fields later, but overall well-structured.

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

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

The tool is complex (multiple data sources, partial failure, timing), and the description covers all necessary context: ecosystem scope, return fields, failure behavior, timing caveats. No output schema, so description compensates fully.

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

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

Schema coverage is 100%, so baseline 3. Description mentions scoped packages and default version, but these are already in the schema. No additional parameter semantics beyond what schema provides.

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

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

The description uses a specific verb ('scan') and resource ('npm package') and clearly states the composite purpose: check license, advisories, bundle size, etc. It distinguishes from siblings by noting it's a composite for npm, while other ecosystems use deps.dev directly.

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

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

Explicitly states when to use: when an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also notes NPM-only in v1 and points to deps.dev for other ecosystems, providing clear context and alternatives.

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

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

Adds behavioral details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and character offsets for verification.

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 4 sentence description, front-loaded with purpose, every sentence adds value, no redundancy.

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

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

Covers purpose, usage, technical details, integration with sibling, and return format (passages with offsets and scores) despite no output schema.

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

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

100% schema coverage; description enriches with examples (e.g., SEC 10-K body, query examples), context for text parameter (already fetched), and cap limit.

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

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

Clearly states semantic search inside a fetched record, specifies verb and resource, and distinguishes from sibling tools like ask_pipeworx_grounded.

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

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

Explicitly advises when to use (when record too large for prompt) and how it pairs with ask_pipeworx_grounded, providing clear alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and no destructive behavior. The description adds that it returns 'ratio, date' and is for price adjustment, which aligns with annotations. No contradictions.

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

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

Single, front-loaded sentence with no wasted words. Every word carries meaning, clearly stating purpose and usage.

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

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

Given the tool's simplicity and the presence of an output schema, the description adequately covers purpose and usage. Could optionally mention more about output format, but it's sufficient.

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

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

Schema coverage is 100%, so description adds minimal value beyond the schema. It mentions 'ratio, date' in the output context, but for input parameters, the schema already fully describes them. Baseline 3 is appropriate.

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

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

The description clearly states it provides historical stock splits (ratio, date) and explicitly mentions the use case of adjusting prices across split events. It distinguishes from sibling tools like dividends, earnings, and price.

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

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

The description explicitly tells the agent when to use this tool ('Use to adjust historical Twelve Data prices across split events'). It lacks explicit 'when not to use' or alternative tools, but the context is clear enough given the sibling list.

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, covering safety and behavior. The description adds useful context about the data returned (exchange and country metadata), but does not disclose additional traits like pagination or rate limits, which is acceptable given 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?

Two concise sentences with no wasted words. The first sentence defines the tool, the second provides usage guidance. Efficient and effective.

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

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

Given the tool's simplicity (reference list with optional filters), the description is complete. Output schema exists, so return values need not be explained. No gaps for the intended use case.

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 input schema already documents all four optional parameters. The description does not add further meaning beyond the schema, which is expected when schema is complete. Baseline 3 is appropriate.

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

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

The description clearly states the tool provides a reference list of supported stock symbols with metadata, and explicitly states its purpose: to discover or validate tickers before querying price endpoints. This distinguishes it from sibling tools like 'price' or 'quote' that handle price data.

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

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

The description explicitly advises using this tool to discover or validate tickers before querying price endpoints, providing clear guidance on when to use it. This differentiates it from price-related siblings.

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 says 'Returns the new subscription id,' implying each call creates a new subscription, which contradicts the idempotentHint annotation (idempotentHint=true). This is a significant inconsistency. On the positive side, it discloses OAuth requirements, delivery caps, and phone verification.

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 appropriately detailed for a complex subscription tool, with clear structure: purpose, authentication, types, delivery. Every sentence provides necessary information 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 lacking an output schema, the description covers return value (subscription ID), authentication, type-specific parameters, and delivery constraints. It does not detail error handling or idempotency, but is otherwise complete for a tool of this complexity.

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

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

Schema coverage is 100%, but the description adds substantial value by explaining enumeration options (e.g., sec_8k, polymarket_edge) with examples, detailing type-specific params, and clarifying delivery options including webhook signing. This goes beyond the schema's minimal 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 to a live-data event stream and returns a new subscription ID. This distinguishes it from sibling tools like list_subscriptions (list) and unsubscribe (remove).

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 specifies that a Pipeworx OAuth account is required, excluding anonymous/BYO users, and notes the SMS 10/day cap and phone verification. However, it does not explicitly mention when to use this tool versus alternatives, though the context makes it clear.

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

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

Annotations already declare readOnly and idempotent. The description adds valuable context: output is drawn from a live catalog, and calling with no arguments yields a full spread while topic focuses results. No contradictions.

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

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

The description is detailed and well-organized, front-loaded with natural language queries, then explanation. Slightly verbose but each sentence adds value; efficient given the complexity.

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

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

Given only one optional parameter and no output schema, the description is complete: it explains input behavior, output structure, and when to use. No gaps for this 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% and the description adds meaning beyond schema: explains that omitting the optional topic gives a cross-category spread, and lists examples ('finance', 'pharma'). No enums but the added examples are helpful.

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: it is the onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It distinguishes from siblings by specifying it is for exploring capabilities, not for direct data retrieval.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you', providing clear when-to-use guidance. It lacks explicit when-not-to-use or alternative tools, but the context is strong.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, establishing safety. Description adds that it computes ONE indicator per call and returns dated indicator values. This aligns with annotations and adds context about call behavior and return format, though no additional limitations or edge cases are mentioned.

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

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

The description is a single focused paragraph that front-loads the core action, then provides examples, usage guidance, and multi-request handling. Every sentence earns its place with no redundancy or filler.

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

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

Given 6 parameters (3 required) and no output schema, the description adequately covers purpose, examples, and handling of multi-indicator requests. It mentions 'Returns dated indicator values' but omits specifics like default outputsize or default time_period (though schema covers those). Overall sufficient for correct invocation, but a brief note on defaults would enhance completeness.

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

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

Schema description coverage is 100% with detailed descriptions for all 6 parameters. The description does not expand on parameter semantics beyond listing indicator examples and giving sample queries. For high-coverage schemas, baseline is 3, and the description adds no further clarification on parameters.

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

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

Description clearly states it computes a technical indicator time series for stocks/forex/crypto via Twelve Data, listing many indicator names (RSI, SMA, EMA, etc.) and providing concrete query examples. It differentiates from sibling tools by positioning itself as the right tool for any technical indicator question and noting it handles one indicator per call.

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

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

Explicitly tells when to use ('PREFER for...', 'right tool for ANY...'), gives clear examples, and instructs how to handle multiple indicators: call once per indicator and do not decline. This provides unambiguous guidance for the agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, confirming safe, non-destructive behavior. The description adds that the tool returns historical OHLC+volume data, aligning with annotations and providing context beyond structured fields.

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

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

The description is two sentences: first states purpose and asset coverage, second specifies required inputs and output. Efficient, front-loaded, and free of unnecessary information.

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

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

Given the rich input schema (100% coverage) and existence of an output schema, the description fully conveys the tool's core functionality. All key aspects (purpose, required params, output shape) are covered without over-explaining.

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 detailed parameter descriptions. The description reinforces required parameters (symbol, interval) and gives examples of valid intervals and symbol formats, adding practical guidance without redundancy.

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

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

The description clearly identifies the tool as providing Twelve Data OHLC time series data for multiple asset types (stocks, forex, crypto, ETFs), specifying the output includes timestamped open/high/low/close and volume. It distinguishes from sibling tools like 'quote' or 'eod' by focusing on historical intraday/aggregated bars.

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 indicates the tool is for historical OHLC data and lists supported asset types, allowing inference of when to use it. However, it does not explicitly state when not to use it or suggest alternatives like 'price' or 'technical_indicator' for other use cases.

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

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

The description adds important behavioral context beyond annotations: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This explains the non-destructive nature and data retention, aligning with the destructiveHint=false 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?

Two sentences, no wasted words. The first sentence states the core action, the second adds crucial detail. Front-loaded and efficient.

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

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

Given the tool's simplicity (1 parameter, no output schema) and good annotations, the description covers all necessary aspects: action, ownership constraint, and data retention behavior. Complete for agent decision-making.

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

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

Schema coverage is 100% with the id parameter described as 'Subscription id (uuid) returned by subscribe.' The description adds no new information beyond the schema, but the parameter is simple and well-documented. Baseline score of 3 is appropriate.

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

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

The description clearly states the action 'Cancel a subscription by id', which is a specific verb+resource. It effectively 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 provides explicit usage guidance with 'Ownership is enforced — you can only cancel your own subscriptions.' This tells the agent when the tool is applicable. No mention of when not to use, but the constraint 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?

Despite strong annotations (readOnly, openWorld, idempotent, non-destructive), the description adds substantial behavioral context: it explains the meaning of 'could_not_verify' (a failed check, not evidence) and 'unsupported' (no source found), and describes the error object verification_error{stage,detail}. This goes well beyond the annotations and clarifies edge-case behavior that agents must handle correctly.

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

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

The description is dense but well-structured, opening with natural-language trigger phrases, then the two processing paths, return values, and critical caveats. Every sentence contributes meaningful detail, though some redundancy exists (e.g., repeated emphasis on 'grounded or structured' evidence). It is appropriately sized for the tool's complexity, but could be tightened slightly without losing value.

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

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

The tool has no output schema, but the description thoroughly enumerates the possible verdicts and the meaning of each, the nature of the returned evidence (grounded or structured with pipeworx:// citation), and the error semantics of could_not_verify. It also clarifies special cases like unsupported. The description is complete enough for an agent to decide when to call and how to 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%, but the description adds value by explaining the 'tolerance_pct' default behavior (implied by claim wording, capped at 5) and its recommended use for hallucination detection (set 1–2). It also gives concrete claim examples that clarify the expected format of the 'claim' parameter.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides specific example phrasings ('fact check', 'verify the claim that...') and distinguishes the tool from any sibling by describing its two execution paths (SEC EDGAR/XBRL fast path for financial claims, grounded pipeline for all others).

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the routing logic for financial vs. non-financial claims. It also notes the tool replaces 4–6 sequential calls, implying when it is more efficient. However, it does not name specific alternative tools or provide explicit 'when not to use' conditions, so it lacks a full exclusion list.

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