Polygon Io

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

Annotations already cover safety (readOnlyHint, idempotentHint, openWorldHint). The description adds value by specifying the data format (timestamped bars, specific fields) and the granularity range, which helps the agent understand behavioral expectations beyond the annotations.

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

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

Two sentences that are front-loaded and concise. First sentence defines the tool, second sentence adds return info and use cases. No redundant or unnecessary text.

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 8 parameters and 5 required, the description covers the essential purpose and main parameters. The presence of an output schema documents return values. Lacks brief mention of optional parameters but overall adequate for the tool's complexity.

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

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

With 0% schema description coverage, the description compensates by explaining core parameters (ticker, granularity via timespan/multiplier, date range via from/to) and gives example values. However, it omits explanations for optional parameters like sort, limit, and adjusted, leaving gaps.

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

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

The description clearly specifies it provides OHLC price bars for a US stock ticker with granularity from 1 minute to quarterly. It lists returned fields (open/high/low/close, volume, VWAP) and distinguishes from sibling tools like previous_close or daily_open_close by focusing on aggregate time series 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?

Explicitly states use cases: charting equities, intraday analysis, backtesting historical prices. Provides clear context for when to use, though lacks explicit exclusions or comparisons to 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 provide readOnly/ idempotent hints. Description adds return format details (score, confidence, signals, raw_response) and cost implication for Anthropic probes ('you pay Anthropic directly'), enriching beyond annotations without contradiction.

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

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

Five sentences, front-loaded with key action and output, no filler. Efficiently covers purpose, usage, parameters, and return format.

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 per-model return object and combined view. Covers all parameters, use cases, and cost implications. Complete for a probing tool with 4 parameters and clear annotations.

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

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

Schema covers 100% of parameters with descriptions. Description adds context: default model, BYO key note, example values like 'Pipeworx', 'Boston restaurant', helping agents use parameters correctly.

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 probes LLMs for visibility scoring (0-100) per model, with specific verb and resource. Distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on generic brand/topic probing for marketing audits.

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

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

Describes default model and optional Anthropic probe with API key. Mentions use cases (AI-marketing audits, pre-launch checks) but lacks explicit when-not-to-use or comparisons to 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 read-only, idempotent, non-destructive, and open-world. The description adds value by explaining the tool routes to 3,558 tools, fills arguments, and returns structured answers with stable citation URIs. No contradiction detected.

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

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

The description is front-loaded with the key guidance ('PREFER OVER WEB SEARCH') and structured in logical order: preference, explanation, usage, examples. It is moderately lengthy but every sentence adds value; only minor redundancy could be trimmed.

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

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

Given the tool's complexity (3,558 tools, many sources), the description covers purpose, usage, behavioral traits, and parameter semantics comprehensively. It mentions returned format (structured answer with citations) even without an output schema. No gaps identified.

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

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

Schema description coverage is 100% with all parameters documented (including aliases). The description does not add significant new meaning beyond clarifying that the question is in natural language and providing examples, but full schema coverage already makes parameters understandable.

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 like 'routes the question', 'returns the structured answer', and contrasts with web search. It clearly identifies the resource (3,558 tools across 823 sources) and distinguishes itself from siblings by stating 'PREFER OVER WEB SEARCH' and listing example domains.

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

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

The description explicitly states preference over web search, provides a comprehensive list of when to use (e.g., SEC filings, FDA data, economic stats), and gives example queries. It also implies when not to use by omission, but the extensive list makes usage very 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?

The description explains behavioral traits beyond annotations, such as the explicit refusal reasons (not_in_source, no_tool_match, etc.), the fact that it uses ONLY tool result, and the extra LLM call cost. This aligns with and enriches the readOnlyHint and idempotentHint annotations.

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

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

The description is front-loaded with the purpose and mode, and every sentence adds value. It is somewhat long but remains focused. Could be trimmed slightly for conciseness, but the structure is effective.

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

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

Given the complexity (6 params all aliases, no output schema), the description explains the output format, refusal reasons, when to use vs sibling, and cost trade-offs. It is thorough and leaves no gaps for the 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?

The input schema has 6 parameters all aliases for question with 100% coverage. The description adds that the question should be in natural language and lists the aliases, providing clarity that any of them work. This goes beyond the schema but could be slightly more specific.

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 hallucination-resistant answer mode for high-stakes reads. It distinguishes itself from the sibling ask_pipeworx by emphasizing that it extracts the answer only from the tool result and notes the extra LLM call cost.

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

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

The description explicitly says when to use this tool (high-stakes reads where answers will be quoted, cited, or acted on) and when not to (prefer ask_pipeworx for casual lookups), providing clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds extensive behavioral details: low-confidence short-circuit behavior, closed/dead market handling, wide-spread market warnings, news fallback fields, and resolver contract specifics. 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 comprehensive but lengthy, covering classifiers, fan-out examples, response shapes, resolver contract, parent event extractor, news fields, and safety. While front-loaded with purpose, it could benefit from bullet points or sections for easier scanning. However, given the tool's complexity, the density is justified.

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

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

Despite no output schema, the description thoroughly details response fields (market, analysis, evidence), resolver contract (confidence levels, alternatives), parent event extraction, news fallback, and safety mechanisms. It covers edge cases like closed markets and low-confidence matches, making the tool's behavior fully predictable without additional documentation.

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

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

Schema coverage is 100%, all parameters are documented. The description adds meaning beyond the schema by providing examples for market_input, explaining depth values ('quick' vs 'thorough'), and adding practical guidance on include_raw (recommended false for response size, true for full payloads). This significantly aids correct invocation.

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

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

The description clearly states the verb 'Research a Polymarket bet' and the resource 'Pipeworx data'. It distinguishes itself from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on single-bet research. The extensive list of classifiers and fan-out examples leaves no ambiguity about its purpose.

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

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

Explicit usage examples are given: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It also guides when NOT to trust results (inspect market_match_confidence) and mentions blocking conditions like low_confidence_match. However, it does not explicitly contrast with siblings like polymarket_edges, leaving some inference to 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?

The description adds valuable behavioral context beyond annotations: it explains the data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), sorting by primary metric, handling of off-calendar fiscal years, and that results include citation URIs. Annotations already indicate readOnly, but description enriches this.

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

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

The description is a single paragraph but well-organized with clear sections for purpose, usage, and behavior. It is concise yet packed with useful information; slight improvement could be breaking into bullet points, but current structure is effective.

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

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

Given no output schema, the description adequately explains what is returned (paired data, citation URIs, sorted results). It covers both entity types comprehensively. Could mention error cases or rate limits, but overall complete for the tool's complexity.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds specific examples (e.g., tickers like 'AAPL', drug names like 'ozempic') and clarifies max/min items, which helps the agent form valid inputs.

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

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

The description clearly states it performs side-by-side comparison of 2–5 companies or drugs in one parallel call. It specifies the verb 'compare' and the resources 'companies' or 'drugs', and distinguishes itself from single-entity tools like ticker_details or entity_profile.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides trigger phrases like 'compare X and Y' and defines when to use the tool versus alternatives.

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

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

Annotations (readOnlyHint, idempotentHint) already indicate safety, but description adds no additional behavioral context such as how after-hours data is handled or what the response contains. Minimal added 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?

Extremely brief (8 words) but sacrifices clarity. Lacks structure and front-loading of key information. Under-specification makes it less useful than a slightly longer but clearer description.

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, the description fails to explain the basic return structure or the meaning of 'after-hours'. Incomplete for a tool with 3 parameters and multiple siblings.

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 0%, but description does not explain any parameter. Does not clarify 'adjusted' or the role of 'date' and 'ticker'. Fails to compensate for lacking schema docs.

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 uses cryptic abbreviation 'O/H/L/C' instead of clear verb+resource. Only slightly clarifies the name, with no differentiation from siblings like 'aggregates' or 'previous_close'. Barely more than a tautology.

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 siblings like 'grouped_daily' or 'previous_close'. No context about prerequisites or when not to use. Entirely missing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns top-N results with examples and that results are ready to call directly, providing additional useful context beyond annotations.

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

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

Single paragraph that is well-structured and front-loaded. Lists usage hints and examples succinctly without waste.

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

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

Despite no output schema, the description fully explains what the tool returns (top-N relevant tools with names, descriptions, full input schemas). Complete for a search tool.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds examples and notes aliases, which is helpful but not transformative.

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

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

Clearly states 'Find tools by describing the data or task' and provides specific examples of data sources (SEC filings, financials, etc.). Distinguishes itself from sibling tools which are specific data tools.

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

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

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear context for when to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that it covers both historical and upcoming data, and lists fields, which is helpful but does not disclose additional behavioral traits like pagination, rate limits, or authentication requirements.

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 short (two sentences) and front-loaded with key information. The second sentence adds use-case guidance, which is useful but not essential. No redundant 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 has 3 parameters with 0% schema coverage and no required fields, the description fails to provide sufficient context for an agent to use the tool correctly. It describes the output well but omits parameter semantics, making it incomplete for a tool with minimal schema hints.

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 0%, so the description must compensate, but it does not explain the parameters (ticker, limit, ex_dividend_date). The ticker is implied but not explicit; limit and ex_dividend_date are unmentioned. The description adds no meaning beyond the schema structure.

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 and upcoming cash/stock dividends for US-listed Polygon.io tickers and lists specific fields (ex-date, pay date, etc.). It also specifies use cases for income analysis and dividend-capture strategies, distinguishing it from sibling tools like 'splits' or 'aggregates'.

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 includes an explicit usage suggestion ('Use for income analysis and dividend-capture strategies'), but does not provide when-not-to-use or mention alternative tools for similar purposes. The guidance is implicit and lacks depth.

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, non-destructive. Description adds value by detailing multi-source fan-out, patent sunset soft-fail, and specific returned data (up to 5 filings with URIs).

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

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

Front-loaded with query examples, then clear purpose and return list. Slightly verbose but every sentence adds value; minor repetition of schema info.

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

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

For a 2-param tool with no output schema, description thoroughly explains inputs, sources, and returned fields. Missing explicit error handling or rate limits, but overall 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 covers both parameters (100% coverage). Description adds extra context: 'type' only supports 'company', 'value' accepts ticker or zero-padded CIK, and clarifies names not supported, plus fallback to resolve_entity.

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 it provides a 'full cross-source profile of a US public company in ONE parallel call', lists example queries, and details returned fields (CIK, filings, fundamentals, etc.). It distinguishes from siblings like 'ticker_details' by being holistic.

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?

Instructions include 'ALWAYS PREFER over chaining single-pack... lookups' and clarify when to use resolve_entity first if only a name is given, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by detailing exactly what data is returned (MIC, name, asset class, type, locale) and the scope of exchanges covered, going beyond the annotations.

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

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

The description is a single, well-structured sentence that front-loads the purpose and returns. Every part adds value without 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?

For a simple reference tool, the description covers what exchanges are included and what fields are returned. However, it omits any mention of optional filtering parameters (locale, asset_class), which reduces completeness. An output schema exists but its content is not provided.

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

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

Schema description coverage is 0%, meaning the schema provides no parameter descriptions. The tool description does not mention the parameters (locale, asset_class) or their purpose, failing to compensate for the lack of 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?

The description clearly states it is a reference list of exchanges, specifying types (US stock, options, crypto, OTC) and the fields returned (MIC, name, asset class, type, locale). This is specific and distinguishes it from sibling tools like tickers or aggregates.

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

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

The description implies usage for obtaining exchange reference data but does not provide explicit guidance on when to use this tool versus alternatives like ticker_details or news. No exclusions or when-not-to-use conditions are mentioned.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description only repeats 'delete' without adding behavioral specifics beyond what annotations already state (e.g., irreversibility, logging, or permissions).

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 short sentences that front-load the purpose and follow with usage guidance. No wasted words.

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

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

For a simple tool with 1 parameter and no output schema, the description plus annotations cover purpose, usage, and parameter. Missing is what the return value indicates (e.g., success message), but the tool is still well-understood.

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 only parameter 'key' is described. The description adds 'by key' but no extra semantics beyond the schema's 'Memory key to delete'. Baseline 3 applies.

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

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

The description states 'Delete a previously stored memory by key' – a specific verb ('Delete') and resource ('memory by key'). It clearly distinguishes itself from sibling tools 'remember' and 'recall'.

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

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

Explicitly says when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with 'remember' and 'recall', providing clear usage context and alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds process details (fetch, extract, emit markdown) and output format, exceeding 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?

Three sentences, front-loaded with purpose, no redundant words. Every sentence adds value.

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

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

No output schema but description explains output as standard markdown blob. Covers core functionality; missing details on error handling or scale gracefully but sufficient for typical use.

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

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

Schema covers both parameters with descriptions. Description adds examples for 'url' and defaults/limits for 'max_links', enhancing practical 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?

Clearly states the verb 'generate' and resource 'llms.txt file' for 'any URL'. Distinguishes from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing on file generation.

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?

Lists concrete use cases: indexing client sites, drafting own project, auditing competitors. Does not explicitly exclude scenarios but provides clear context for when to use.

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

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

The annotations already indicate a safe, read-only operation. However, the description adds no additional behavioral details (e.g., what 'grouped' means, output structure, date handling). It barely contributes beyond the annotations.

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

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

The description is extremely short (three words), but this is under-specification rather than conciseness. The phrase 'All-ticker daily.' is not meaningful and lacks structure—it does not form a complete sentence that communicates the tool's function.

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, the description is entirely insufficient. It does not explain the grouping logic, how it differs from similar tools, or the meaning of parameters. For a tool with 2 params and many siblings, this is critically incomplete.

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 0%, and the description provides no explanation for either parameter ('date' or 'adjusted'). The schema only lists types, lacking format, units, or effect of the boolean flag. The description adds zero 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 'All-ticker daily.' is a vague phrase that does not clearly state the tool's purpose. It fails to specify what operation is performed (e.g., retrieve, list, aggregate) and does not differentiate from sibling tools like 'daily_open_close' or 'aggregates'.

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?

There is no guidance on when to use this tool versus alternatives. The description does not mention context, prerequisites, or typical use cases. With multiple daily-related tools, an explicit comparison is missing.

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

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

Annotations already declare readonly and nondestructive behavior; description adds return fields and parameter detail, enhancing transparency beyond annotations.

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

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

Two sentences efficiently convey purpose, returns, and usage; no wasted words and front-loaded with key information.

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

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

For a simple readonly list tool with one optional param and no output schema, the description fully covers what an agent needs: what it does, what it returns, and when to use it.

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

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

Schema description covers the only parameter at 100% coverage; description does not add further meaning beyond what the schema provides.

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

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

The description clearly states the verb 'list' and the resource 'subscriptions,' specifies the caller's scope, and distinguishes from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

Explicitly advises when to use: 'review what you're monitoring before adding more' and 'find an id to cancel,' providing clear contextual direction.

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, so safety profile is clear. The description does not add behavioral context such as what exactly 'upcoming' means (time range), which holidays are included, or any limitations.

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

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

Description is extremely concise at two words, with no wasted content. It is front-loaded and communicates the core purpose immediately.

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, the description lacks context about scope (e.g., which exchanges or regions), date range for 'upcoming', and how data is ordered. For a tool with zero parameters, more context would significantly aid understanding.

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?

No parameters exist, and schema description coverage is 100% trivially. Description adds no parameter info, which is acceptable because there are none.

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 'Upcoming holidays.' clearly states the tool returns list of upcoming holidays. It is a specific resource (holidays) with implied verb (list). While very brief, it distinguishes from sibling tools like 'market_status' or 'daily_open_close' which are different concepts.

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 vs alternatives like 'market_status' or 'exchanges'. Given the tool is a simple list with no parameters, usage is straightforward, but explicit context would help.

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, indicating a safe, read-only operation. The description adds no additional behavioral context, such as what the output looks like or any rate limits, missing an opportunity to enhance transparency beyond annotations.

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

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

The description is very concise at one short sentence, but it is too vague to be effective. It does not fully earn its place as it lacks specificity; a more informative single sentence would be better. The structure is minimal but not harmful.

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

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

Given the tool has zero parameters and an output schema exists, the description should still clarify the nature of 'market status' (e.g., returns a string indicating open/closed or a boolean). It does not provide enough context for an agent to understand what the tool returns or 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?

There are no parameters, so the schema coverage is 100% by default. The description adds no param information, but with zero parameters, the baseline expectation is met. No additional meaning is required from the description for input semantics.

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

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

The description 'Current market status' clearly indicates the tool provides market status, but it is vague as it does not specify what 'status' entails (e.g., open/closed, trading hours). It does not differentiate from sibling tools like daily_open_close or market_holidays, which have overlapping domains.

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 provided on when to use this tool versus alternatives such as daily_open_close or market_holidays. The description lacks any context about prerequisites, use cases, or exclusions, leaving the agent without direction.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds context about output content (publisher, URL, image, summary, sentiment) without contradicting annotations. No rate limit or freshness info, but sufficient given annotations.

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

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

Two sentences, front-loaded with core purpose, followed by usage guidance and comparison. 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?

Despite having output schema and good annotations, description lacks parameter guidance for 5 optional parameters. Missing explanations for sort, order, published_utc, etc., which are not self-explanatory from names alone.

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 0%. Description does not explain any of the 5 parameters (sort, limit, order, ticker, published_utc). Examples in schema provide minimal guidance, but description adds no parameter semantics.

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

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

Clearly states it provides Polygon.io financial news with ticker-tagged US stock market headlines, including publisher, URL, image, summary, and sentiment. Distinguishes from web search for equity-focused news.

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 using for queries like 'what is the news on $TICKER' or 'market-moving headlines today', and prefers over web search for equity news. No explicit when-not-to-use or alternatives among sibling tools, but context is clear.

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

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

Annotations are all false/neutral, so the description carries the burden. It discloses rate limiting (5 per identifier per day), that it's free and doesn't count against quota, and that the team reads digests daily. This adds useful behavioral context beyond annotations.

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

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

The description is concise with six short, information-dense sentences. It is front-loaded with purpose and uses, followed by important usage constraints. Every sentence adds value with no redundancy.

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

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

Given the tool's moderate complexity (3 params, 2 required, nested object, no output schema), the description covers all essential aspects: purpose, usage contexts, message guidelines, rate limits, and quota impact. It is fully adequate for an agent to use 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 parameters. The description adds value by advising to describe issues in terms of Pipeworx tools/packs, not to paste end-user prompts, and to be specific with 1-2 sentences. This goes beyond the schema's parameter 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 is for telling the Pipeworx team about broken, missing, or needed functionality, listing specific categories (bug, feature/data_gap, praise). It distinguishes itself from sibling tools which are mostly data retrieval tools.

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

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

The description explicitly lists when to use this tool (bug, feature/data_gap, praise) and provides usage constraints like rate limits and quota-free status. It does not explicitly state when not to use, but the guidance is clear and sufficient for an 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 readOnly, idempotent, openWorld. Description adds data source (CF analytics-engine), privacy (no PII), caching (5min-1h), and aggregation style. 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?

Concise, well-structured with bullet use cases, no redundant sentences. All information 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?

Single optional parameter, no output schema. Description covers return contents, caching, and behavioral semantics fully. 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 already describes enum with short explanation. Description adds context about window durations (surface hot vs steady-state). Adds value beyond schema.

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

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

Description states verb (returns) and resource (top tools, packs, call volume). Clear differentiation from siblings like discover_tools or aggregates.

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

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

Explicitly lists three use cases and explains window semantics. Lacks explicit when-not-to-use or alternative mentions.

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. The description adds substantial context: monotonicity checks, partition-sum deviations, Jaccard similarity threshold, placeholder filtering, and response structure. No contradiction with annotations.

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

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

The description is dense and well-organized with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER). While lengthy, every sentence contributes meaning. Could be slightly more concise by grouping related details.

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

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

Covers both modes, response structure, and constraints comprehensively. Lacks explicit mention of the response format for topic mode (though likely similar to event mode). Also does not specify behavior when both parameters are supplied.

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 explaining mode behavior, providing example slugs, and describing the effect of each parameter. Could elaborate on error handling if both are provided.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between single-event and cross-event modes with specific examples, making it distinct from sibling tools like polymarket_edges.

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

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

Explicitly requires one of 'event' or 'topic', warns against no-arg calls. Provides clear guidance on when to use each mode: event for specific markets, topic for cross-event scanning. Also mentions constraints like Jaccard similarity and partition filter.

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 a safe, idempotent, non-destructive operation. The description adds extensive behavioral details: edge calculation net of slippage, Kelly fractions, 24h move warnings, caching, and diagnostics. This goes far beyond what annotations provide, giving the agent a clear model of tool behavior.

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

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

The description is comprehensive but lengthy, containing over 400 words with dense technical details. It is well-structured with sections and front-loaded main purpose, but could be more concise without losing essential information.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is remarkably complete. It explains model families, edge calculation, response structure, diagnostics, and caching. An agent can fully understand the tool's behavior and output without additional documentation.

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. The overall description adds contextual meaning to parameters like min_partition_leg_kelly and explains how knobs interact (e.g., min_kelly vs min_partition_leg_kelly). This adds value beyond the schema, though the schema already does well.

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 Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also includes the user goal 'what should I bet on today,' making the intent explicit. The tool is well-differentiated from siblings like polymarket_arbitrage by its specific methodology.

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

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

The description explains the tool's usage context, including the three response segments and tradeable-edge knobs, but does not explicitly compare it to alternatives or state when not to use it. However, the rich detail on segments and knobs provides clear guidance on leveraging the tool.

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

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

Annotations already mark as read-only, idempotent, non-destructive. Description adds deep behavioral context: explains spread calculation (Kalshi - Polymarket), safety fields (compatibility_warning, temporal_alignment), and conditions for non-equivalent bet shapes with concrete examples. No contradiction with annotations.

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

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

Description is lengthy but information-dense. Every sentence provides necessary context for a complex tool. Could be slightly more concise, but structure is logical (purpose, modes, response, safety). Front-loads core purpose.

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

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

Covers all essential aspects: two modes, response structure including leg-by-leg prices and spreads, safety fields with detailed conditions, temporal alignment. No output schema, but description partially compensates. Lack of return value format is the only gap.

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

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

Schema covers all 3 parameters with full descriptions. Description enhances with explicit list of topic macros, examples, and explanation of how kalshi_event_ticker and polymarket_event_slug override topic-mapped sides. Adds value beyond schema.

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

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

Clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. Distinct verb 'spread' and resource description. Distinguishes from siblings by focusing on cross-venue comparison, not single-venue or general arbitrage.

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

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

Provides two modes (topic shortcuts or explicit event IDs) with examples. Warns that pre-mapped topics often return compatibility warnings, setting realistic expectations. Does not explicitly compare to polymarket_arbitrage sibling, but the niche is clear.

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

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

Annotations already provide safety profile (readOnlyHint, idempotentHint, etc.). The description adds zero behavioral context beyond what annotations offer. No mention of data freshness, error conditions, or return structure.

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

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

The description is only two words, which is under-specification rather than conciseness. It lacks any structured information and does not earn its place as a minimal but complete explanation.

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 is radically insufficient. It does not convey what the tool returns, how to use it, or any contextual details. Agent cannot reliably invoke this tool based on the description alone.

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 0% and the description does not explain the 'ticker' or 'adjusted' parameters. It provides no insight into their meaning, constraints, or effects.

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 is a tautology: 'Previous close.' repeats the tool name without specifying the action or what it returns. No verb is used, making it unclear whether it gets, sets, or displays data. Among siblings like 'daily_open_close', it fails to distinguish itself.

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. There is no mention of similar tools like 'daily_open_close' or 'aggregates', nor any context about prerequisites or typical 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by confirming the read-only nature, explaining scope (by identifier), and the list-all behavior when key is omitted. No contradiction.

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

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

Description is one efficient paragraph, front-loaded with the main action. Every sentence adds value: purpose, usage context, scoping, and sibling pairing. 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?

For a read-only tool with one optional parameter and no output schema, the description covers the function, usage context, scoping, and relationships. Could optionally mention return format, but not required given the 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% and already states that omitting the key lists all keys. The function description does not add new parameter semantics 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?

Description clearly states verb ('retrieve') and resource ('value previously saved via remember'), distinguishing it from sibling tools like 'remember' and 'forget'. It also specifies the dual behavior of retrieving a single key or listing all keys.

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 explains when to use ('look up context the agent stored earlier') and provides scoping details. While it doesn't explicitly state 'when not to use', the context of sibling tools and the pairing with 'remember' and 'forget' gives clear guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating safe, idempotent, non-destructive behavior. The description adds details on return content (source, citation_uri, raw payload) and confirms polling is fine, providing behavioral context beyond annotations.

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

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

The description is four sentences, efficiently conveying purpose, return content, filtering options, and usage context. No redundant or 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?

Despite no output schema, the description explains the return fields (source, citation_uri, raw payload). It covers the side effect of mark_read, confirms polling suitability, and mentions an alternative access method. This is complete given the 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 coverage is 100% with descriptions for all 5 parameters. The description adds value by giving an example for 'type' (e.g., 'sec_8k') and explaining the side effect of 'mark_read: true'. This goes beyond the schema descriptions, enhancing understanding.

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

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

The description clearly states it pulls fired events from subscription feed, specifying the resource (alerts) and the action (pull). It distinguishes from siblings by focusing on recent alerts from a persisted feed, unlike tools like 'subscribe' or 'list_subscriptions' which handle subscription management.

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 clear context for use (pulling alerts from feed, polling works, alternative access via URL). However, it does not explicitly state when not to use this tool versus alternatives like 'news' or 'list_subscriptions', though the purpose is distinct enough.

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

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

The description discloses detailed behavioral traits beyond the annotations: it fans out to multiple APIs, specifies fallback behavior (GDELT preferred, GNews when rate-limited or 5xx), notes the USPTO API sunset and soft-fail, and describes the output structure. The annotations already mark it as read-only, idempotent, non-destructive, and open-world, and the description adds valuable context without contradiction.

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

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

The description is thorough and front-loaded with user-focused examples (e.g., 'What's new with X'). Every sentence adds value, but the length is slightly high due to detailed enumeration of data sources and fallback behavior. Still, no redundant information exists.

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

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

Given the tool's complexity (multiple sources, fallback, date parsing) and lack of an output schema, the description is very complete. It describes the output format (changes grouped by source, total_changes, citation URIs) and the behavior under different conditions. The open-world hint is respected, and the description covers all necessary aspects for an agent to use 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?

While the schema already describes all three parameters with 100% coverage, the description adds significant value: it provides concrete examples for 'since' (ISO date or relative shorthand like '7d', '30d', '3m', '1y'), explains that 'value' accepts ticker or CIK, and notes that 'type' currently only supports 'company'. This interpretation of the schema is highly informative.

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 change feed for companies, aggregating data from multiple sources (SEC, GDELT/GNews, USPTO) in a single parallel call. It explicitly distinguishes itself from the sibling tool 'entity_profile' by noting the latter is for static profiles, not time-windowed changes. The purpose is specific, actionable, 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?

The description provides clear guidance on when to use this tool (for change feeds over a time window) and when to use the alternative 'entity_profile' (for static profiles). It also suggests typical 'since' values like '30d' or '1m'. However, it does not explicitly mention when to choose this over other sibling tools like 'news' or 'daily_open_close', which could be relevant for monitoring 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?

Description adds value beyond annotations: explains memory scope ('scoped by your identifier'), persistence duration (24 hours for anonymous, persistent for authenticated), and implies write nature. No contradiction with annotations.

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

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

Four sentences, front-loaded with core purpose, no redundant information. Each sentence adds value.

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

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

Given simple schema (2 params, no output), description covers behavior, usage, lifecycle, and pairing with other tools. Sufficient for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline 3. Description provides example usage for key parameter (e.g., 'subject_property') but does not add substantial new semantics beyond the schema descriptions.

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

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

Description clearly states 'Save data the agent will need to reuse later' with specific verb 'save' and resource 'data'. It distinguishes from siblings like recall and forget, making the purpose unambiguous.

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

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

Explicitly says 'Use when you discover something worth carrying forward' with examples. Mentions pairing with recall and forget. However, no explicit statement of when not to use, but context is clear.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds valuable context: it cascades through multiple internal endpoints, auto-disambiguates for companies, and returns citation URIs. No contradictions.

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

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

The description is front-loaded with examples, uses bullet points for types, and every sentence adds value. Slightly lengthy but justified by content density.

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 two simple parameters and no output schema, the description fully covers expected behavior, return format, and use cases, including citation URIs and auto-disambiguation.

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 enriches both parameters by explaining exact return formats for each type (ticker+CIK+URI for company, RxCUI+ingredient+brand for drug) and acceptable input formats.

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

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

The description starts with clear examples of user queries ('What's the ticker for…') and explicitly states the tool resolves names to canonical identifiers. It also distinguishes itself from siblings by noting it replaces 2-3 manual lookups.

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

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

The description advises 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It does not explicitly state when not to use it, but the context is clear.

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

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

Annotations indicate read-only, idempotent, and non-destructive behavior. The description adds detail: it internally calls ai_visibility_check for each entity, ranks by score, and returns score, confidence, and 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?

The description is succinct, front-loaded with the core purpose, and every sentence adds meaningful 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 no output schema, the description lists return fields (score, confidence, signal density) and explains the process. It covers the main functionality but lacks details on error handling or edge cases like empty 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 that the first entity is treated as the subject for narrative, and how models and _apiKey relate. This clarifies intent beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, and ranks them. It distinguishes itself from the sibling ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the process and output.

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

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

The description provides a concrete use case (competitive AI-marketing audits) and an example query. While it doesn't explicitly state when not to use it, the context and sibling tools imply alternatives like ai_visibility_check for single entities.

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, destructiveHint. The description adds significant behavioral details: fans out across sources, returns summary block, partial failures degrade gracefully, bundlephobia first measurement takes 5-30s, sources_failed lists 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 dense but well-structured, front-loading the core purpose and then providing details. Every sentence adds value, though slightly verbose. Still efficient for the amount of information conveyed.

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

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

Given the complexity (composite tool, no output schema), the description covers all critical aspects: returned data fields, partial failure behavior, timing, ecosystem scope. It compensates completely for the lack of output schema by listing return fields and behaviors.

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

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

Schema coverage is 100% with both parameters fully described. The description adds no new parameter semantics beyond the schema (package name, version defaults). Baseline 3 is appropriate as the schema carries the full burden.

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

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

The description clearly states the tool's purpose: a composite check for adding an npm package, aggregating data from deps.dev and bundlephobia. It specifies the exact data returned and distinguishes from siblings by noting NPM-only scope and referencing deps.dev:version for other ecosystems.

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 about safety, popularity, size, or cost of adding an npm package. Also provides a clear exclusion: NPM ecosystem only in v1, with alternatives for other ecosystems mentioned. Lacks explicit 'do not use for X' but context is strong.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by disclosing the embedding model (BGE-base-en), windowing strategy (500-char overlapping windows), and input cap (200K chars with truncation flag). It also mentions that each passage carries an offset 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?

The description is concise yet comprehensive, around 150 words. It is front-loaded with purpose, then usage, pairing, and technical details. Every sentence serves a clear purpose 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?

Given no output schema, the description adequately explains return values (top-N passages with offsets and scores). It covers input constraints, model behavior, and verification support, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds examples for the 'query' parameter (e.g., 'supply-chain risk') and specifies the default value and range for 'limit' (1-20, default 5), providing practical guidance beyond the schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, specifying the action ('search INSIDE'), the resource ('fetched record'), and the output ('passages with character offsets and similarity scores'). It distinguishes itself from sibling tools like ask_pipeworx_grounded by explaining their complementary roles.

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

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

The description explicitly states when to use: 'Use when the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded. While it doesn't explicitly list when not to use, the context is clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so description adds detail on output fields but doesn't disclose additional behavioral traits 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?

Single sentence with no wasted words, front-loaded with key information.

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

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

Output schema is present, so return values are covered elsewhere. However, the description lacks parameter details (e.g., execution_date format, limit semantics) making it only partially complete for a tool with 3 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?

Schema has 3 parameters with 0% description coverage. The description does not explain the meaning or format of any parameter, leaving the agent to infer from examples or assume 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?

Description clearly states the tool returns historical stock splits with split ratio, execution date, and ticker for US-listed Polygon.io tickers. Distinguishes from siblings like dividends and aggregates.

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 case: 'Use to adjust historical price comparisons across split events.' Provides clear context but no explicit 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?

The description directly contradicts annotations. Although it details behavior (creation, delivery caps), annotations mark readOnlyHint=true and idempotentHint=true, which are inconsistent with a creation operation that returns a new ID each time. This contradiction undermines transparency.

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

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

The description is front-loaded with the main purpose and provides necessary detail. While slightly verbose, every sentence adds value, and the structure is logical.

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 (nested objects, no output schema), the description covers subscription type, params, delivery options, prerequisites, and return value. It is complete for a creation tool, with sibling tools handling other lifecycle actions.

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

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

Schema coverage is 100%, baseline 3. The description adds significant value by explaining the type enum, defaulting of items in params, delivery channel specifics, and SMS rate caps, going beyond the schema 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 clearly states the tool creates a proactive monitoring subscription, specifies the supported type (sec_8k), and explains the purpose (pings on new 8-K filings). It distinguishes from siblings like 'unsubscribe' and 'list_subscriptions' by indicating this is the create action.

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

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

The description provides clear context on when to use (creating a subscription) and includes prerequisites (requires Pipeworx OAuth account). It explains delivery channels but does not explicitly state when not to use or compare to 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, openWorldHint, idempotentHint, and destructiveHint. The description adds no behavioral context beyond the name, failing to describe main behavior or side effects. 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 extremely concise (one phrase) but lacks structured information. It is not verbose, but the brevity comes at the cost of substance.

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?

While an output schema exists (so return values are not required), the description fails to fully articulate the tool's purpose. Given the simplicity, a more complete description (e.g., 'Get reference details for a stock ticker') would be expected.

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 0% description coverage for the single 'ticker' parameter. The description does not explain the parameter's meaning, expected format, or example values. The tool name only partially clarifies.

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 'Ticker reference detail' implies the tool provides details for a specific ticker, but it is vague and does not explicitly state that it retrieves reference data for a given ticker. The tool name clarifies intent, but the description could be more specific.

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

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

No guidance on when to use this tool versus siblings like 'tickers' (which likely lists tickers) or 'entity_profile'. The description provides no context for selection or exclusion.

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 behavior. The description adds that it searches a reference universe and returns specific fields, but no additional behavioral details like rate limits or error handling.

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 waste. Efficiently communicates purpose and output.

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 8 undocumented parameters and no output schema details shown, the description is incomplete. It lacks guidance on how to use parameters effectively.

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 0% and the description offers no explanation of the 8 parameters (sort, type, limit, etc.). The examples in the schema provide some clues, but the description fails to add meaning.

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

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

The description clearly states the tool searches Polygon.io for multiple ticker types (stocks, options, etc.) and returns specific fields. However, it does not explicitly differentiate from sibling tools like 'ticker_details'.

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 provides a concrete use case ('resolve a company name to a tradable symbol') but does not mention when not to use it or suggest 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 describes writing behavior (canceling a subscription) while annotations set readOnlyHint=true and destructiveHint=false, creating a direct contradiction. Despite the description being transparent about the mutation, the inconsistency with annotations severely impairs reliability.

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, each adding distinct value: purpose + ownership, then effect + relation to sibling. 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?

For a simple tool with one parameter and no output schema, the description covers purpose, ownership, mutation type, and impact on data. It also connects to a sibling tool (recent_alerts). Completely 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?

Schema covers the single parameter fully with description. The description adds semantic context by stating ownership restriction (only your own ids), which helps the agent understand the parameter's valid values 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 'Cancel a subscription by id', using a specific verb and resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by indicating that this tool cancels rather than creates or lists.

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

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

Explicitly states ownership enforcement: 'you can only cancel your own subscriptions.' Also explains the consequence of deactivation and relation to 'recent_alerts', providing clear when-to-use and what-not-to-use guidance.

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

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

Annotations already indicate read-only and safe operations. The description extends transparency by detailing the return format (verdict, structured form, actual value with citation, percent delta) and noting it replaces multiple sequential calls, giving the agent a clear behavioral model.

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

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

The description is well-structured and front-loaded with trigger phrases and purpose. While it is detailed, every sentence adds meaningful context, but it could be slightly more concise without losing information.

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

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

Given the tool's single parameter and no output schema, the description comprehensively covers purpose, usage domain, expected input, and output structure, leaving no critical gaps for the 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 a comprehensive description for 'claim'. The description adds value by providing example input strings and clarifying the expected natural-language format and supported claim types, enhancing the schema's information.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides explicit trigger phrases and specifies the domain (company-financial claims for public US companies via SEC EDGAR), distinguishing it from sibling tools.

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

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

The description explicitly says when to use the tool: 'whenever the agent needs to check whether something a user said is factually correct.' It also defines the scope (company-financial claims) but lacks explicit exclusions for other claim types, which would improve guidance.

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