Polygon Io

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds return structure (OHLC+VWAP+volume) and data source (Polygon.io), providing 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?

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

Given output schema exists, description covers core return fields and typical usage. Lacks mention of authentication or rate limits common with Polygon.io, but examples mitigate some ambiguity.

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

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

Schema description coverage is 0%, so description must compensate, but it only mentions granularity range (timespan/multiplier) via example, leaving 6 other parameters (e.g., sort, adjusted) unexplained beyond property names.

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 OHLC price bars for US stock tickers from Polygon.io with granularity from 1 minute to quarterly, differentiating it from siblings like daily_open_close or previous_close.

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 suggests use cases (charting, intraday analysis, backtesting), providing clear context for when to invoke, though it does not list alternatives or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and not destructive. The description adds valuable context: default model, BYO key for Anthropic with cost implications, and return format (per-model score, confidence, signals, raw_response).

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 about 4 sentences, front-loaded with the core purpose, then default model, return format, and use cases. Every sentence adds value; no redundancy.

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

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

Despite no output schema, the description fully explains return values (per-model + combined). Parameters are well-documented, annotations cover safety, and use cases are given. The tool's behavior is completely understandable.

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 concrete examples for 'entity' (e.g., 'Pipeworx'), clarifies the role of '_apiKey' (only needed for Anthropic), and explains 'context' for disambiguation. This goes beyond the schema descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and returns a visibility score (0-100). It distinguishes from siblings like 'ask_pipeworx' and 'scan_competitor_ai_presence' by focusing on quantitative scoring across multiple models.

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

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

The description explicitly lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring), providing clear context. However, it does not explicitly contrast with similar sibling tools like 'scan_competitor_ai_presence'.

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

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

Annotations already indicate a safe, read-only, idempotent tool. The description adds context: routes to 4,482 tools, fills arguments, returns structured answer with stable citation URIs. No contradictions. Minor gap: does not detail error handling or query routing logic.

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

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

Front-loaded with key directive ('PREFER OVER WEB SEARCH') and use cases. Dense but not overly verbose; every sentence contributes. Could be slightly leaner without losing value.

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

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

Explains purpose, usage, alternatives, and parameter well. No output schema, but description indicates return value (structured answer with citations). Sufficient for a high-level query tool.

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

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

Schema covers 100% of parameters (single 'question' with aliases). Description provides example values but does not add significant semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states that the tool routes questions to a vast set of data sources and returns structured answers with citations. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit guidance on when to use this tool (default for factual questions, e.g., 'what is', 'look up') and when to step up to alternatives (hallucination-resistant single answer or broad multi-part queries). Includes concrete examples.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: extraction only from tool results, explicit refusal reasons, and the extra LLM call cost. No contradictions.

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

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

The description is a single, well-structured paragraph. Key information is front-loaded (purpose, routing), followed by usage guidance, behavioral details, and cost trade-off. No unnecessary repetition.

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

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

Despite no output schema, the description specifies the return format (fields like answer, evidence, refusal_reason) and covers all essential aspects: purpose, usage, behavior, parameters, and cost. The annotations provide safety context, making it complete for evaluation.

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 parameters are well-documented. The description does not add new parameter-level meaning beyond acknowledging aliases, which is already in schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It explains the routing mechanism and explicitly distinguishes from sibling `ask_pipeworx` by highlighting the extraction step and refusal logic.

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

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

The description provides explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on' and lists example high-stakes domains. It also warns against casual use and recommends `ask_pipeworx` instead, including a cost trade-off note.

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 extensive behavioral detail: fan-out logic, classifiers, response shapes, resolver contract with confidence levels, safety short-circuits, parent event extraction, and resolution-rule risk. No contradictions.

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

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

The description is detailed and well-structured with clear headings (CLASSIFIERS, FAN-OUT EXAMPLES, etc.), but longer than necessary. Some redundancy could be trimmed. Still, the structure aids readability and the detail is justified by tool complexity.

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

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

No output schema exists, so the description must explain return values, which it does comprehensively (result.market, result.analysis, result.evidence, market_match_confidence, parent_event, news fields, safety mechanisms). Covers edge cases (low confidence, closed markets, wide spreads, cancellation rules). Fully sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100%, providing descriptions for all three parameters. The description additionally clarifies how 'market' can be slug, URL, or question text; explains 'depth' options with default; and describes 'include_raw' with guidance on when to use true. Adds significant value beyond schema.

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

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

The description clearly states the verb ('Research') and resource ('a Polymarket bet'), distinguishing it from siblings like ask_pipeworx and polymarket_edges. It specifies that it pulls Pipeworx data in one call and returns an evidence packet plus comparison.

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

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

Explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). Does not explicitly exclude alternatives, but the context strongly implies when to use this versus sibling tools. Clear and helpful.

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 readOnlyHint=true, idempotentHint=true, etc. The description adds significant behavioral detail: it pulls latest 10-K data for companies (handling off-calendar fiscal years), FAERS data for drugs, sorts results by primary metric, and returns citation URIs. No contradictions with annotations.

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

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

The description is dense and informative but lacks structured formatting like bullet points. It could be slightly more concise for easier scanning, though every sentence contributes value.

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

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

Given the complexity and absence of an output schema, the description covers key aspects: input examples, data sources, sorting, and citation URIs. It could more explicitly list output fields for each type, but overall it is sufficiently complete.

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

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

Input schema covers all parameters with 100% description coverage. The description enhances semantics by providing concrete examples for company and drug values, and explaining what data is pulled for each type, adding value beyond the schema.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2–5 companies or drugs in a single parallel call. It provides example queries ('X vs Y', 'which is bigger'), distinguishes from sequential single-pack lookups, and explains the data sources and output format.

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 directs agents to prefer this tool over sequential lookups when comparing entities, and gives concrete examples of when to use it. However, it does not explicitly mention when not to use it, such as for a single entity query.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds that it fetches 'official' prices and includes after-hours/pre-market data, but does not mention any side effects, authorization needs, or rate limits. This is adequate given the annotations.

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

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

Single sentence with front-loaded verb 'Fetch'. All key information is included without unnecessary words. Very efficient.

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

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

An output schema exists, so return values are not needed. The description provides the source, data fields, and date format. However, it omits the 'adjusted' parameter, which is part of the input schema. Overall adequate but not fully complete for a tool with multiple optional parameters.

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

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

Schema coverage is 0%, so the description must explain all parameters. It covers 'ticker' and 'date' (including format YYYY-MM-DD) but does not mention the optional 'adjusted' parameter, leaving it undocumented. This is a significant gap.

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 fetches specific financial data (open, high, low, close, volume, after-hours/pre-market) for a US stock ticker on a specific date from Polygon.io. However, it does not differentiate from sibling tools like 'previous_close' or 'aggregates', which may have overlapping functionality.

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 (e.g., 'aggregates' for multiple dates, 'previous_close' for only previous close). No prerequisites or exclusions 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 indicate read-only, idempotent, and non-destructive behavior. The description adds substantial context: parallel decomposition, 15-60s execution, return format (findings packet with evidence, gaps, citations), and constraints (not open-web search). 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 long but every sentence adds necessary context. It is front-loaded with critical account requirement and alternatives. Minor redundancy (e.g., repeating 'structured data' multiple times) but overall well-structured.

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

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

The tool is complex (parallel research across many sources), but the description covers inputs, outputs, constraints, and comparison with siblings. Output schema is absent, but the description details the return format (findings packet, gaps). Sufficient for an agent to decide and invoke correctly.

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

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

Both parameters (question, depth) are fully described in the schema. The description adds practical details: depth enum values explained (quick=3, standard=5, thorough=8 paid) and that question can be broad/multi-part. Schema coverage is 100%, and description enriches understanding beyond the schema.

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

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

The description clearly states the tool's purpose: grounded multi-source research across structured data sources. It distinguishes itself from sibling tools like ask_pipeworx by specifying scope (structured data only, not open-web search) and use case (broad/multi-part questions).

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 this tool vs. ask_pipeworx: for broad/multi-part questions over structured data, and warns against using for breaking/current news. Also includes account prerequisite and paid plan requirement for 'thorough' 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 declare readOnlyHint=true and idempotentHint=true. The description adds that returns top-N tools with full schemas and curated examples, ready to call directly—enhancing beyond annotations. No contradictions.

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

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

Four sentences, each serving a purpose: purpose, usage, return value, timing advice. Front-loaded with key action. No wasted words.

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

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

Given 6 params (1 required), no output schema, description explains return format (names, descriptions, schemas with examples) and that results are directly callable. Sufficient for the tool's discovery role.

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

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

Schema coverage is 100% (baseline 3). Description adds context: explains that query accepts natural language descriptions, lists aliases (task, q, search, description), and provides examples. Adds value beyond bare schema.

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

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

Description clearly states 'Find tools by describing the data or task' and lists specific domains (SEC filings, FDA drugs, etc.), distinguishing it from sibling tools like search_within or ai_visibility_check which operate on data rather than tool discovery.

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 need to browse, search, look up, or discover what tools exist for...' and advises 'Call this FIRST when you have many tools and want to see the option set (not just one answer).' This gives clear when-to-use and sequencing 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 provide readOnlyHint and idempotentHint, so the description does not need to repeat safety. It adds useful behavioral context: scope (US-listed Polygon.io ticker), listing specific data fields provided, and that it covers both historical and upcoming dividends.

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, two sentences, front-loaded with key information. However, it could be more efficient by including parameter details without significantly lengthening it.

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

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

Given there is an output schema, return values need not be described. The description covers scope and purpose but omits parameter semantics and potential data constraints (e.g., date range for ex_dividend_date), leaving some gaps for a tool with 3 parameters and no schema descriptions.

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 the description does not explain the meaning of 'limit' or 'ex_dividend_date' parameters. It mentions 'ticker' indirectly by stating 'US-listed Polygon.io ticker,' but lacks full parameter clarification. The example in the schema partially compensates but is not part of the description.

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

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

The description clearly states it provides historical and upcoming cash and stock dividends for a US-listed ticker, listing specific fields (ex-date, record date, etc.) and a use case. No sibling tool offers dividends, so it is well-distinguished.

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

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

The description explicitly says 'Use for income analysis and dividend-capture strategies,' providing clear context for when to use it. It does not mention exclusions or alternatives, but sibling tools are sufficiently different to imply when to use this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating safe read-only operation. The description adds useful context beyond notifications: the parallel fan-out across sources, the soft-fail for patents (USPTO sunset), and fallback mechanisms (GDELT→GNews). It also explains the return structure (CIK, filings, fundamentals sorted, etc.). While it doesn't discuss rate limits or error handling, the behavioral traits are well-covered given the annotation support.

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

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

The description is lengthy but well-structured: it front-loads with examples and a clear purpose, then details sources and return fields. Every sentence adds value—examples, constraints, fallback notes. It could be slightly more concise by removing the very long list of sources, but overall it is efficient and well-organized for an AI agent.

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

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

Given no output schema, the description provides a thorough summary of what to expect: CIK, recent filings (up to 5 with URIs), fundamentals (latest 10-K with specific fields), patents with soft-fail notice, news via fallback, and LEI. It mentions sorting and format. While some details like pagination or exact field names are missing, the description is rich enough for an AI agent to understand the tool's behavior and output.

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

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

Schema description coverage is 100%, with each parameter having a description in the schema. The tool description adds additional meaning: clarifying that 'type' is currently limited to 'company', and that 'value' can be a ticker or zero-padded CIK but not a name. It reinforces the constraint from the schema and adds the detail about name resolution via resolve_entity. This goes beyond the schema's descriptions, earning a 4.

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

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

The description starts with concrete example queries ("Tell me about X", "research Acme") and clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call.' It lists specific data sources (SEC, XBRL, USPTO, news, GLEIF) and return fields, distinguishing it from sibling tools by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' This is a specific verb+resource with clear scope and differentiation.

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

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

The description explicitly tells when to use the tool: when the user asks for a holistic view of a US public company. It gives usage precedence over chaining other lookups. It also states a clear exclusion: 'names not supported (use resolve_entity first if you only have a name).' This provides both when and when-not guidance, along with an alternative tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. Description adds that returns MIC code, name, asset class, type, locale, which provides useful behavioral details beyond annotations. No contradiction.

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

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

Single sentence is concise and front-loaded with the core purpose. Every word adds value, no fluff.

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

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

Given the presence of an output schema, the description sufficiently covers the tool's behavior for a reference list. It mentions the types of exchanges and return fields. Could be improved by noting null or default behavior for 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 2 parameters (locale, asset_class) with 0% description coverage. Description does not explain these parameters or their acceptable values. While it hints at asset classes (stocks, options, crypto), it lacks clarity on how to use them for filtering.

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 what the tool does: provides a reference list of exchanges covered by Polygon.io, specifying US stocks, options, crypto, OTC. The verb 'Reference list' and resource 'exchanges' are specific and distinct from siblings 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?

Usage is implied as a lookup for exchange metadata, but no explicit guidance on when to use this vs. alternatives like 'ticker_details' or 'market_status'. No exclusion criteria or prerequisites 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. Description adds context about why to delete (sensitive data) and does not contradict annotations.

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

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

Two sentences, no wasted words. Front-loaded with action and 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?

Tool is simple with one parameter, no output schema, and annotations present. Description fully explains purpose, usage, and pairing, making it complete.

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

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

Schema coverage is 100% with one parameter 'key' described as 'Memory key to delete'. Description does not add meaning beyond what the schema provides, so baseline 3.

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

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

Description clearly states 'Delete a previously stored memory by key'—specific verb and resource. Sibling tools include 'remember' and 'recall', so it distinguishes from related operations.

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 context is stale, the task is done, or you want to clear sensitive data'. Also advises pairing with siblings 'remember and recall'.

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 and idempotent; description adds behavioral detail (fetches page, extracts title/description/links, emits markdown) without contradiction. Discloses output format and non-destructive nature.

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

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

Single paragraph, front-loaded with purpose, covers key points without waste. Could be slightly more structured but is efficient.

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

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

Given the tool's simplicity (2 params, no output schema), the description fully explains functionality, process, and use cases, leaving no ambiguity.

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

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

Schema description coverage is 100%, so baseline is 3. Description repeats URL and max_links defaults but adds no additional semantic context beyond what schema provides.

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

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

Clearly states the tool generates a production-ready llms.txt file for any URL, with specific verb+resource and distinct use cases (client indexing, own project, competitor audit), differentiating it from siblings.

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

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

Provides explicit use cases (indexing, drafting, auditing) but does not mention when to avoid using it or alternatives. The context is clear enough for selection.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds value beyond these by specifying the data source ('Polygon.io'), the batch nature ('in a single call'), and the scope ('all US stocks'). It aligns with annotations and provides useful behavioral context.

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

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

The description is a single efficient sentence with no filler. Every part contributes meaning: action, resource, scope, format, source, and use case.

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 only two parameters, an output schema (documenting return values), and comprehensive annotations, the description is complete. It tells the agent what the tool does, why it's useful, and the date format needed.

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

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

Schema description coverage is 0%, so the description must compensate. It adds format guidance for 'date' ('YYYY-MM-DD') but does not mention the 'adjusted' boolean parameter. This partial coverage (1 out of 2 parameters) is insufficient for full clarity.

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

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

The description clearly states 'Fetch OHLCV bars for all US stocks on a given date' with specific verb 'fetch', resource 'OHLCV bars', scope 'all US stocks', and format 'YYYY-MM-DD'. The use case 'market-wide snapshot or screening' adds context, distinguishing it from sibling tools like 'daily_open_close' or 'previous_close'.

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 use case ('useful for market-wide snapshot or screening') but does not explicitly state when to use this tool versus alternatives like 'aggregates' or 'ticker_details'. No exclusions or when-not-to-use guidance are given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds value by listing the returned fields (id, type, etc.), but does not disclose any additional behavioral traits such as pagination or rate limits.

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

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

The description is concise with two sentences. The first sentence states the core purpose, and the second provides usage guidance. No unnecessary information.

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

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

Given the tool's simplicity (no required parameters, one optional boolean, rich annotations), the description is complete. It covers purpose, return values, and usage context.

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

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

Schema coverage is 100% with a clear description for the single parameter. The description does not add any further context about parameter usage 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 action (list), resource (subscriptions), and scope (caller's active). It 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?

The description explicitly advises when to use this tool: to review monitored subscriptions before adding more or to find an id to cancel. It does not explicitly state when not to use, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds that the data is from Polygon.io and the specific fields returned, providing context 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?

The description is a single sentence that is concise and front-loaded with the essential purpose. Every word contributes meaning, with no redundancy or verbosity.

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

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

Given the tool has zero parameters, comprehensive annotations, and an output schema (as indicated by context signals), the description adequately covers the purpose, source, and return fields. It is complete for an agent to understand and invoke the tool correctly.

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

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

The tool has no parameters, so the description does not need to explain parameter meaning. Baseline score of 4 is appropriate as schema coverage is 100% and description adds no parameter details, which is acceptable.

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 the tool returns a list of upcoming US stock market holidays, including date, holiday name, and exchange status. It uses a specific verb 'Return' and resource 'list of upcoming US stock market holidays', distinguishing it from siblings like market_status.

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 retrieving holiday data but does not explicitly state when to use this tool over alternatives like market_status or other market data tools. However, the context of sibling tools may help an agent infer the appropriate use case.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds no further behavioral context beyond stating it returns current status. No mention of rate limits, data freshness, or other traits.

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 (3 words), which is concise but lacks substantive information. While front-loaded, it does not earn its place as it adds minimal value beyond the title.

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 no parameters and annotations cover safety, the description is still incomplete. It does not explain what 'market status' means (e.g., open/closed, holiday schedule, or index values). The output schema exists but is not referenced.

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, and schema coverage is 100%. The description does not need to add parameter details. A score of 4 is baseline for zero parameters.

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

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

The description 'Current market status' is a tautology of the title 'Market Status'. It lacks a verb or specific action, making it vague about what the tool does. Siblings like 'daily_open_close' and 'previous_close' have clearer purposes, and this description does not 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 is given on when to use this tool versus alternatives. With many market-related sibling tools such as 'daily_open_close', 'previous_close', and 'ticker_details', the agent has no criteria for selecting this tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering safety and idempotency. The description adds that the tool returns articles with publisher, URL, image, summary, and sentiment, which is 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 two sentences, front-loaded with the tool's purpose and immediately followed by use cases and a comparative recommendation. Every sentence adds value with no wasted words.

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

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

Output schema exists, so return details are covered. However, the lack of parameter descriptions means the agent may not know valid values for 'sort', 'order', or 'published_utc' format. The two examples help but are insufficient for full completeness.

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

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

With 0% schema description coverage, the description should compensate but does not explain each parameter's meaning, allowed values, or constraints. Examples in the schema suggest usage (e.g., ticker='AAPL', limit=10), but no formal parameter semantics 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?

Description clearly states it provides Polygon.io financial news with ticker-tagged US stock market headlines, including specific details like publisher, article URL, image, summary, and sentiment. Use cases are explicitly given, and it distinguishes itself from sibling tools as the dedicated news tool.

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

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

Description gives explicit use cases: 'use for "what is the news on $TICKER" or "market-moving headlines today"'. It also advises preferring this tool over web search for equity-focused news, providing clear guidance on 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 description adds significant behavioral context beyond annotations: it's free, doesn't count against quota, rate-limited to 5 per identifier per day, team reads daily, and feedback affects roadmap. There is no contradiction with annotations.

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

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

The description is concise, approximately 4 sentences, with no redundant information. It front-loads the purpose and efficiently covers all necessary guidance.

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 moderate complexity (3 params, nested object, no output schema), the description thoroughly covers purpose, usage, behavioral traits, and parameter semantics, making it complete for agent decision-making.

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

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

Schema coverage is 100% with detailed descriptions. The description adds value by advising to be specific, use 1-2 sentences, and mention which tool/error. This slightly improves clarity 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 it is for sending feedback to the Pipeworx team, listing specific categories (bug, feature, data_gap, praise). This distinguishes it from all sibling tools which are data retrieval or analysis 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 specifies when to use: for bugs, feature requests, data gaps, or praise. It also gives a clear instruction to not paste end-user prompts, guiding proper usage.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds value by explaining data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h), which go 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?

One paragraph with clear enumeration of use cases. Every sentence adds value; no wasted words. Could be slightly more structured, but it's 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?

No output schema exists, but description explains return values (top tools, top packs, total call volume) and caching. For a simple read-only tool, this is complete enough.

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

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

Schema coverage is 100% for the single parameter (window). Description adds semantic meaning about window choices (shorter=hot right now, longer=steady-state), enriching the enum choices.

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

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

The description clearly states the tool returns trending data (top tools, top packs, total call volume) over a configurable window. It uses specific verbs and differentiates itself from siblings like 'discover_tools' which likely lists all 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?

Provides three explicit use cases (discovering hot data sources, confirming canonical tool choice, seeing alignment). Lacks explicit when-not-to-use or alternatives, but the use cases are clear.

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

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

Despite comprehensive annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false), the description adds significant behavioral context: it explains the internal checks (monotonicity violations, partition-sum, Jaccard similarity), the partition filter for placeholders, and the fill check using live CLOB depth. It discloses that realizable edge ≤ 0 means no trade, aligning with the non-destructive and read-only hints. No contradictions found.

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

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

The description is lengthy but well-structured with logical sections (event mode, topic mode, semantic anchor, partition filter, fill check). Every sentence provides necessary information, though some repetition exists (e.g., the fill check is mentioned twice). It could be slightly more concise, but the structure aids readability and information retrieval.

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 (two modes, multiple checks), the description is remarkably complete. It defines response structure (opportunities array, partition_check object), handles edge cases (no args fails, placeholder filtering, low similarity), and references a sibling tool for custom sizing. The absence of an output schema is compensated by the detailed response description, ensuring the agent knows what to expect.

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

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

Both parameters have descriptions in the schema, but the description adds substantial value beyond those. It explains the semantic difference between event and topic modes, provides concrete examples (e.g., 'fed-decision-may-2026', 'Strait of Hormuz traffic'), and details the processing each mode triggers (walking child markets vs. cross-event scanning). This enriches the agent's understanding of how to use each parameter effectively.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools by specifying two distinct modes (event and topic) and detailing the algorithmic approach. The verb 'find' and resource 'arbitrage opportunities' are precise, and the description differentiates from similar tools like polymarket_edges and polymarket_fill_risk.

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

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

The description explicitly requires either 'event' or 'topic' parameter, warning that calling with no arguments fails. It recommends event mode for specific markets and topic mode for cross-event scanning, providing clear guidance on when to use each. It also advises against trading when the fill check indicates non-realizable edges, offering explicit alternatives like polymarket_fill_risk for custom sizing.

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

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

Annotations declare readOnlyHint and idempotentHint, which are consistent. The description adds valuable details: caching at KV level, diagnostic fields for empty segments, edge calculations after slippage, and per-leg Kelly behavior in partitions. No contradiction found.

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

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

The description is detailed but well-structured, front-loading the purpose then diving into model families, response format, knobs, and caching. Every sentence serves a purpose, though lengthy for a quick skim. It balances completeness with organization.

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

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

Despite no output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics), edge metrics, and tradeable-edge filters. It covers caching and why Fed bets are excluded, leaving no major gaps.

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

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

Schema coverage is 100%, so the description adds extra context beyond schema definitions, such as examples (e.g., setting min_liquidity to 5000) and reasoning (e.g., slippage defaults based on Polymarket liquidity). This enhances understanding without being redundant.

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

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

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, and it distinguishes itself from generic browsing by being built for 'what should I bet on today'. It specifies the three model families and the unique value proposition.

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

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

The description provides explicit guidance on when to use the tool (discovery without paging hundreds of markets) and includes tradeable-edge knobs and warnings about Fed bets. However, it does not explicitly contrast with sibling tools like 'polymarket_arbitrage' or provide clear 'do not use when' conditions.

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

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

Annotations already indicate readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds detailed behavioral traits: limits on history depth (60-day snapshot TTL), data source ('daily closes of edge_pp_net'), and explanation of gaps ('snapshots are written when polymarket_edges runs on a cache-miss'). Response structure is fully described, including edge cases.

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

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

The description is well-structured: starts with core purpose, then args, then response fields (tracked, expired, snapshot_dates), then limits. Every sentence serves a purpose with no fluff. It is front-loaded with the key insight about edge age, making it easy for the agent to grasp.

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 of time-series edge telemetry, the description covers all aspects: how data is structured (time-series, first_seen, trend, decay), what expired means (closed, resolved, arbed away), and limitations (60-day TTL, intraday not supported). No output schema exists, but the description compensates with detailed return structure.

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

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

Schema coverage is 100% with both parameters described. The description adds extra semantic context beyond the schema: default values (14 for days, '1wk' for window), clamping range (2-30), and semantic description of window as 'snapshot family'. This adds value, but the schema already does heavy lifting.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots. Answers "how long has this edge existed and is it shrinking?"' It uses specific verbs ('tracks', 'answers') and contrasts a fresh wide edge with an old one, distinguishing it from siblings like polymarket_edges that likely provide only current snapshot data.

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

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

The description provides context on when to use: 'a fresh wide edge and a 3-week-old wide edge are different trades'. It implies this tool provides historical persistence, but does not explicitly state when not to use or name alternatives. The sibling list includes polymarket_edges, which is the likely alternative, but no direct comparison is made.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds behavioral context like walking the ladder, returning verdicts, and explaining that theoretical overround may not be capturable. This goes beyond annotations by detailing the analysis nature and risk factors, though annotations already cover safety.

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

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

Despite length, every sentence is informative. Structured with a summary, requirements in bold, mode-specific details, and actionable usage notes. No wasted words. Front-loaded with key 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?

No output schema exists, but description thoroughly lists return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, etc.) and mentions additional context like thin_legs and forced_directional_risk. Fully covers what the agent needs to understand 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 description coverage is 100%, but the description adds significant meaning: clarifies how size_usd is interpreted differently per mode (max spend vs target proceeds vs settlement notional), explains side defaults, and provides constraints like clamp range. This elevates understanding beyond schema.

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

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

Description clearly states the tool performs a realizable-vs-theoretical edge check against live order-book depth, distinguishes between single-market and basket modes, and explicitly tells when to use it before other related tools like polymarket_arbitrage and polymarket_edges. The verb 'check' and resource 'order-book depth' are specific and distinct from siblings.

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

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

Provides explicit guidance: use before acting on arb signals or edges trades above $500. Explains two modes with clear when-to-use conditions (single-market vs basket) and warns about risks of partial fills converting arb into directional positions. No ambiguity.

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 extensive behavioral details: response structure, compatibility warnings, temporal alignment, skipped counters, and conditions for non-equivalent bet shapes.

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

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

Well-structured with clear sections (purpose, modes, response, safety fields). Slightly verbose but every sentence adds value; front-loaded with key concepts.

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

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

Despite no output schema, description thoroughly explains response fields and safety warnings. Covers edge cases and temporal alignment, making it complete for a read-only comparison tool.

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

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

Schema covers 100% of parameters. Description adds context: lists all topic shortcuts, explains overriding behavior, and gives format examples for explicit tickers, going beyond schema descriptions.

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

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

Clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. Distinct from siblings like polymarket_arbitrage which focus on single-venue 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?

Explains two modes (topic shortcuts vs explicit tickers) and when to use each. Notes that real spreads are rare and pre-mapped topics may not be tradeable, guiding appropriate invocation.

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

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

Annotations already declare readOnlyHint and idempotentHint, making the safety profile clear. The description adds that the data comes from Polygon.io, which provides source context. However, it does not disclose behaviors like data recency, handling of missing sessions, or authentication needs, which would add value beyond annotations.

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

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

The description is a single, well-structured sentence that packs all essential information without any fluff. Every word carries meaning, making it efficient and easy to process.

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 that an output schema exists, the description does not need to explain return values. However, the lack of parameter explanation for 'adjusted' and the absence of guidance on when to use this tool versus siblings like 'daily_open_close' leaves it incomplete for a complex context with many sibling tools.

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

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

Schema description coverage is 0%, so the description must compensate. It implicitly explains the 'ticker' parameter by mentioning 'US stock ticker', but does not explain the 'adjusted' boolean parameter at all. This is insufficient compensation, leaving the agent unclear about an important optional parameter.

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

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

The description clearly states the verb 'Fetch', the resource 'previous trading session's open, high, low, close, and volume', and the scope 'US stock ticker from Polygon.io'. This uniquely identifies the tool and distinguishes it from siblings like 'daily_open_close' and 'aggregates' which may serve different timeframes or data types.

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

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

The description implies when to use (fetch previous session data) but does not explicitly state when not to use or mention alternatives like 'daily_open_close' or 'aggregates'. With many sibling tools, explicit guidance would help correct selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds scoping by identifier and listing behavior. No contradictions.

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

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

Two compact sentences front-loaded with purpose, then usage, scope, pairing. Every sentence adds value with no 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?

For a simple retrieval tool with no output schema, description covers purpose, usage, scope, and pairing. Could mention return values or error handling for missing keys, 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 coverage is 100%, so baseline is 3. Description adds context about omitting key to list all keys, which aids usability beyond schema description.

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

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

Clearly states the action (retrieve/list), resource (saved values/keys), and scope. Distinguishes from siblings by mentioning paired tools 'remember' and 'forget'.

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

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

Explicitly tells when to use (look up stored context) and provides examples (ticker, address, notes). Implicitly contrasts with re-deriving from scratch. Mentions pairing with remember/forget.

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 useful behavioral context: the mark_read parameter affects future calls by flagging events as read, and mentions the feed persistency and polling suitability. 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 reasonably concise with a few sentences. It front-loads the main purpose and includes key details. Minor redundancy in explaining 'mark_read' could be trimmed, but overall efficient.

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

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

Covers main functionality and return fields, but omits explanation of the 'unread_only' parameter and does not clarify sorting order or limit behavior. The alternative endpoint mention is helpful, but missing unread_only reduces completeness for a tool with 5 optional parameters.

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

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

Schema coverage is 100%, but the description adds value by providing examples (e.g., 'type' with 'sec_8k'), explaining the combination of filters (type and/or since), and clarifying the effect of mark_read. This goes beyond the bare schema descriptions.

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

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

The description clearly states 'Pull fired events from your subscription feed' using a specific verb and resource, and further details the content of alerts (source, citation_uri, raw event). It distinguishes itself from siblings like list_subscriptions by focusing on alert events from the persisted feed.

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 that polling works fine and provides an alternative direct API endpoint for scripts/dashboards, guiding when to use the tool versus the raw endpoint. However, it lacks explicit comparison to sibling tools or conditions when not to use it.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds significant behavioral context: fans out to multiple sources, fallback logic, soft-fail for USPTO, and return 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?

Description is well-structured, starting with example queries. While slightly long, every sentence adds value—no redundancy. Could be more concise, but effectively front-loads 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?

Given high complexity (multi-source, fallback, soft-fail, relative dates) and no output schema, description is remarkably complete. It explains all sources, fallback logic, parameter semantics, return structure, and points to sibling for alternative use. No gaps.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds value by explaining 'since' formats with examples (ISO date vs relative), suggesting typical values like '30d', and noting that 'type' only supports 'company'. This extra guidance justifies a 4.

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

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

Description clearly states the tool provides a change feed for companies, with specific verb ('change feed for a company') and resource ('recent changes'). It explicitly distinguishes from sibling 'entity_profile' by stating when to use that alternative instead.

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

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

Explicitly provides when to use (e.g., 'What's new' queries) and when not to use (use entity_profile for static profile). It also describes fallback behavior between GDELT and GNews, giving clear context for tool selection.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false; description adds that saving is a key-value store, with 24-hour retention for anonymous and persistent for authenticated. No contradiction, but could explicitly state overwrite behavior consistent with idempotency.

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 concise sentences covering purpose, when, scoping/retention, and pairing. Front-loaded with core action; no wasted words.

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

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

Given two simple parameters, no output schema, and annotations present, description sufficiently covers when and how to use, scoping, retention, and pairing with siblings. 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 covers both parameters with descriptions; description adds context by mentioning key-value pair and general examples (ticker, address, preference), but does not substantially enhance parameter meanings beyond schema.

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

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

The description clearly states the tool saves data for reuse across conversations or sessions, specifying verb 'Save' and resource 'data'. It distinguishes from sibling tools 'recall' and 'forget' by mentioning pairing, making the purpose distinct.

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

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

Explicitly advises when to use: 'when you discover something worth carrying forward.' Also explains scoping by identifier, persistence differences between authenticated and anonymous users, and explicitly pairs with recall/forget for retrieval/deletion, providing 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 indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context about internal cascading lookups and that it replaces 2-3 manual searches, enhancing transparency without contradiction.

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

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

The description is concise yet informative, with front-loaded example queries making the purpose immediately clear. Every sentence contributes value, though slightly verbose with internal details.

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

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

Despite no output schema, the description thoroughly explains return values for each type (ticker, CIK, company_name for company; RxCUI, ingredient, brand for drug) and includes citation URI formats, making it complete for a lookup tool.

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

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

Schema coverage is 100%, but the description adds meaning by explaining the value parameter's accepted formats (ticker, CIK, name for company; brand/generic for drug) and the type parameter's enum options, going beyond the schema's basic descriptions.

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

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

The description clearly states that the tool resolves a user-spoken name to the canonical/official identifier, with specific examples like 'What's the ticker for...' and 'find the CIK for...'. It distinguishes itself from siblings by emphasizing its role as the first step when an ID is needed.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear usage guidance. It does not explicitly state when not to use, but the directive is sufficiently clear for decision-making.

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

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

Annotations already provide readOnly, idempotent, non-destructive hints. Description adds that it probes each entity with ai_visibility_check and returns a ranked list with specific fields. Also discloses model dependencies and API key requirement for anthropic.

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

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

Three sentences, each essential: action+result, mechanism, use case. No redundant 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?

No output schema exists, but description sufficiently describes return: ranked list with score, confidence, signal density. Combined with schema for entities count, it provides complete understanding for a compound probing tool.

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

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

Schema covers all parameters (100% coverage). Description adds significant value: explains entities order (first is subject, rest competitors), context disambiguation, and models with free vs paid options.

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, ranks them by score, and surfaces most/least recognized. It distinguishes from sibling ai_visibility_check (single entity) and mentions using it internally.

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: competitive AI-marketing audits with example question. Implies when to use but does not explicitly state when not to use or alternatives beyond ai_visibility_check.

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

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

Annotations indicate readOnlyHint, idempotentHint, destructiveHint=false. Description adds behavioral traits: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list timeouts. No contradiction.

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

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

The description is relatively long but well-structured and front-loaded with purpose. Almost every sentence adds value; minor redundancy could be trimmed but overall efficient.

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

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

Given the complexity (multi-source composite check), the description covers inputs, behavior, edge cases (partial failures, timeouts), output summary fields, limitations (NPM only). Without an output schema, it adequately explains return values.

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 2 parameters with 100% description coverage. Description adds context: scoped packages accepted for package param, and defaults to latest version when omitted. This adds meaning beyond the schema.

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

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

The description clearly states it's a composite check for adding npm packages, covering license, advisories, version history, bundle size, etc. It uses specific verbs and resources and distinguishes from sibling tools by mentioning NPM ecosystem only.

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: 'whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. Also specifies NPM ecosystem only and notes other ecosystems fall under deps.dev:version directly.

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

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

Annotations already declare readOnlyHint=true and no destructive action. The description adds technical behavior: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' This provides useful context beyond what annotations offer.

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

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

The description is four sentences, front-loaded with the core function. Every sentence adds value: use case, benefit, pairing, and technical details. No wasted words.

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

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

For a tool with 3 parameters, no output schema, and good annotations, the description fully covers return format (passages with offsets and scores), technical details (embeddings, window, truncation), and complementary tools. Nothing essential is missing.

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

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

Schema coverage is 100% with all parameters described. The description largely echoes schema details (e.g., max ~200K chars, limit range, query examples). It adds no significant new meaning beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Semantic search INSIDE a fetched record.' It specifies the input (text and natural-language query) and output (top-N passages with character offsets and similarity scores). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

The description explicitly states when to use: 'Use when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter.' It also mentions a complementary tool (ask_pipeworx_grounded) for grounding over passages. Lacks explicit when-not-to-use, but the positive guidance 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 indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds context that data is historical and specific to US-listed Polygon.io tickers, which is useful beyond annotations. No contradictory information is present.

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

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

The description is extremely concise: two sentences with no redundant words. It is front-loaded with the core function and ends with a practical usage hint. 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?

For a simple data retrieval tool with a well-defined output schema and strong annotations, the description provides adequate high-level context. However, it lacks details on parameter interactions, default behavior, and potential error conditions. The presence of an output schema offsets some gaps but the parameter documentation is insufficient.

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 parameters. The description does not explain parameter semantics (e.g., what 'limit' controls, format for 'execution_date'). While parameter names are somewhat intuitive, the lack of detail forces reliance on external knowledge. The description should compensate for the schema gap but fails to do so.

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

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

The description clearly states the tool returns historical stock splits for a US-listed Polygon.io ticker, including split ratio, execution date, and ticker. It also provides a specific use case of adjusting historical price comparisons. However, it does not explicitly differentiate from sibling tools like aggregates or dividends, which could be competitors.

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

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

The description gives a clear usage scenario: 'Use to adjust historical price comparisons across split events.' This implies when to use the tool. However, it does not explicitly state when not to use it or mention alternative tools for similar purposes.

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 include idempotentHint=true, which aligns with 'create' behavior. The description adds useful behavioral details beyond annotations: per-type parameter semantics, delivery channel constraints (SMS 10/day cap, webhook auto-disabled after 10 failures), and idempotency implied. 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 the core purpose, but is quite long due to detailed type examples and channel explanations. While informative, it could be slightly more concise without losing value, but 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 (3 parameters with nested objects, 5 enum types), the description covers all necessary aspects: type-specific filters, delivery options, prerequisites, and behavioral constraints. No output schema exists, but the description sufficiently explains return values ('new subscription id').

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

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

Schema coverage is 100%, but the description adds substantial meaning: it explains type-specific params for each enum value (e.g., sec_8k items codes, polymarket_edge topics) and delivery channel limitations. This goes well beyond the bare schema.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This is a specific verb+resource, clearly distinguishing it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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 a prerequisite: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' It lists supported types with examples, but does not explicitly mention when not to use or name alternatives. However, the context of sibling tools like unsubscribe is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral context: it's the onboarding entry point, returns example questions with exact tool+argument shape from the live catalog. No contradictions and adds value 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 fairly long but well-structured: starts with trigger questions, then describes output, then usage. It front-loads the purpose and each sentence adds value, though some 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 absence of an output schema, the description adequately explains the output format (category-bucketed example questions with tool+argument shape). It covers the tool's purpose and behavior for a low-complexity tool with a single optional parameter.

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

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

The schema provides description for the single optional parameter 'topic' with enum-like suggestions. The description adds meaning by stating 'Omit for a cross-category spread', which clarifies usage beyond the schema. Schema coverage is 100% so baseline is 3, but the extra guidance earns a 4.

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

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

The description explicitly states the tool returns category-bucketed example questions for Pipeworx, lists trigger phrases, and describes its role as the onboarding entry point. It clearly distinguishes from sibling tools like ask_pipeworx 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?

The description says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions alternatives like meta-tools. It also specifies optional topic filtering. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds value by listing the return fields (company name, description, SIC code, etc.), which is beyond the annotations. No behavioral contradictions. However, it does not disclose error handling or rate limits, keeping score from a 5.

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?

A single 21-word sentence that front-loads the main action and lists key fields. No fluff. Every word earns its place.

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

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

Given the tool has only one parameter and an output schema exists (reducing need to explain return values), the description is fairly complete. It covers the tool's purpose and the main content returned. Lacks mention of edge cases (e.g., invalid ticker) but acceptable for a simple fetch 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?

Input schema has 0% description coverage for the 'ticker' parameter. The description only mentions 'single ticker' without adding format, examples, or constraints. With only one parameter, the description could easily include a brief note (e.g., 'NASDAQ symbol like AAPL') but does not, leaving the agent to guess.

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

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

Description clearly states it fetches full reference details for a single ticker and lists specific fields (company name, description, SIC code, etc.). This sets it apart from sibling tools like 'tickers' (which likely lists tickers) and 'entity_profile' (which may be more general). Verb 'Fetch' is specific, and resource 'full Polygon.io reference details' is well-defined.

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

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

No guidance on when to use this tool vs alternatives. Sibling tools like 'aggregates', 'daily_open_close', 'entity_profile' might provide similar data, but the description does not differentiate usage context or provide any example scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds useful behavioral context by specifying the returned fields (symbol, name, market, etc.) and the scope of search (US stocks, options, indices, etc.), which goes beyond annotations.

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

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

Two concise sentences: first states what it does and returns, second gives a specific use case. Front-loaded, no fluff.

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

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

Given the presence of an output schema (not shown), return values are covered. However, the tool has 8 parameters with no schema descriptions, and the description does not fill that gap. For a search tool with many optional filters, more context on parameter usage is 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?

With 0% schema coverage and 8 parameters, the description provides no parameter-specific guidance. It only implicitly mentions 'search' by referring to 'company name', but does not explain sort, limit, market, etc. The examples in the schema partially compensate, but description itself is insufficient.

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 for tickers across multiple asset types and returns key fields. It also specifies the use case 'resolve a company name to a tradable symbol', making the purpose highly specific and distinguishable 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?

The description explicitly states the primary use case ('Use to resolve a company name to a tradable symbol'), providing clear guidance. However, it does not mention when not to use it or reference alternative sibling tools, which would improve differentiation.

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

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

Goes beyond annotations by explaining the row is deactivated not deleted, and that historical events remain accessible via recent_alerts. This adds valuable behavioral context that annotations (idempotentHint, destructiveHint) do not fully cover.

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 pack all essential information without redundancy. Front-loaded with the core action, then ownership and deactivation details. No wasted words.

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

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

For a simple tool with one parameter and no output schema, the description provides complete context: purpose, ownership constraint, idempotent/deactivation behavior, and linkage to related tool (recent_alerts). No gaps.

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

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

Schema description coverage is 100% for the single parameter 'id'. The description does not add additional meaning beyond the schema's definition, but the baseline of 3 is appropriate given full schema coverage.

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

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

Description clearly states action ('Cancel a subscription by id') and resource ('subscription'), distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'. Title also reinforces 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?

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when to use. Lacks explicit when-not or alternative references, but the constraint itself is strong 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, open-world, idempotent, non-destructive. Description adds details: returns verdict types, structured form, actual value with citation, percent delta. Discloses use of SEC EDGAR + XBRL. No contradictions.

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

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

Description is informative but slightly lengthy (3 sentences). Front-loaded with examples and purpose. Every sentence adds value, but could be tightened slightly.

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 return types (verdict, structured form, citation, delta). Mentions replacement of sequential calls, giving context on efficiency. Covers key aspects for a complex tool.

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

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

Schema coverage is 100% for the single parameter. Description provides natural-language context and examples, but adds no structural detail beyond schema. Baseline 3 is appropriate.

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

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

Clearly states the tool verifies natural-language factual claims, specifically for company-financial data. Differentiates from siblings by mentioning it replaces 4-6 sequential calls. Verb+resource+scope are specific.

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

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

Explicitly says 'Use whenever...' and provides example phrasings. Mentions scope limitation to company-financial claims in v1. Could be improved by stating when not to use (e.g., non-financial claims), but context makes it clear.

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