Odds Api

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

Annotations declare read-only, idempotent, non-destructive. Description adds details on output format (per-model results + combined), payment for Anthropic calls, and default model. 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?

Three sentences: main action, detail on models/API key, usage examples. Front-loaded and every sentence adds value without redundancy.

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

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

Given moderate complexity, good schema coverage, and no output schema, the description fully explains input, behavior, output structure, and use cases. No missing critical information for selection.

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

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

Schema descriptions cover all parameters (100% coverage). Description adds context: default model, meaning of _apiKey (BYO key, direct payment), and models array. Explains 'context' parameter for disambiguation.

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 probes LLMs for AI visibility of an entity and scores it. It distinguishes from siblings by focusing on visibility scoring and listing sibling tools like 'scan_competitor_ai_presence'.

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

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

Provides context for when to use (AI-marketing audits, brand checks) and explains default model and API key requirement. Does not explicitly exclude alternatives but implies use cases.

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

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

Annotations already indicate readOnlyHint=true and openWorldHint=true. The description adds context that the tool internally routes to one of 4,552 tools across 1,160 sources, fills arguments, and returns structured answers with citation URIs. This goes beyond the annotations but still leaves some details unspecified (e.g., 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 well-structured with a clear heading and key points. However, it is somewhat lengthy and contains some redundancy (e.g., listing many domains). The front-loading of the core message is effective.

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

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

Given the tool's complexity (routing to many sources), the description covers what the tool does, when to use it, and what the output looks like (structured answer with citations). No output schema exists, but the description adequately explains the return format.

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 six parameters, all aliases for 'question'. Schema coverage is 100%, so the description doesn't add much beyond noting that it accepts natural language questions. Examples are provided, but no additional semantics about parameter values or constraints are given.

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

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

The description clearly states the tool's purpose: it should be preferred over web search for factual questions about structured data from authoritative sources. It lists specific domains (SEC filings, FDA, etc.) and 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?

The description provides explicit guidance on when to use this tool ('START HERE for most questions') and when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions). It also mentions that for breaking news, ask_pipeworx already routes to relevant sources.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds critical behaviors: it costs an extra LLM call, returns explicit refusal reasons when data is insufficient, and uses only tool results. 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 well-structured: first sentence front-loads the core purpose, followed by routing details, refusal behavior, and usage guidelines. While comprehensive, it is appropriately sized for the complexity and does not waste words.

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

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

Despite the lack of an output schema, the description fully explains the return format on success and failure, including fields like evidence, confidence, and refusal reasons. It also covers the extra cost and typical use cases, 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 description coverage is 100% with each parameter alias described. The tool description adds no further parameter meaning beyond listing aliases, so baseline 3 is appropriate.

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

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

The description clearly defines the tool as a 'hallucination-resistant answer mode for high-stakes reads,' specifying its output structure (answer, evidence, refusal reasons) and distinguishing it from the sibling 'ask_pipeworx' by stating it extracts answers using only tool results and costs an extra LLM call.

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

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

The description explicitly states when to use this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples like financial verdicts. It also advises against use for casual lookups, directing to 'ask_pipeworx' instead.

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 (readOnly, idempotent, non-destructive) are fully consistent. The description adds extensive behavioral details: low-confidence short-circuit, closed market handling, wide-spread tradeability, resolution-rule risk, news fallback mechanisms, and parent event extraction. Far exceeds what annotations provide.

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

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

Very detailed but somewhat verbose (multiple paragraphs). However, it uses clear headings (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES) and structured lists, which aids scanning. Could be slightly more concise without losing critical info.

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

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

Given the tool's complexity (multiple data sources, edge detection, resolver contracts) and lack of output schema, the description is exceptionally complete, covering all edge cases, safety mechanisms, and field interpretations.

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

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

Schema coverage is 100%, but the description enriches meaning: explains depth (quick vs thorough), include_raw (size control), and market input types with examples. It adds value 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?

The description clearly states it researches Polymarket bets by pulling Pipeworx data, and specifies input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). It distinguishes from sibling tools like polymarket_edges and get_event_odds by offering comprehensive, category-specific data fan-out.

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

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

Explicit usage strings: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' with concrete fan-out examples for different bet types. It guides when to inspect result fields like market_match_confidence before trusting analysis.

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

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

Adds significant detail beyond annotations: for companies, pulls latest 10-K data from SEC EDGAR/XBRL with fiscal year handling; for drugs, FAERS counts, FDA approvals, trials. No contradiction with readOnlyHint etc.

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?

Packed with information but slightly verbose. Each sentence adds value, but could be more streamlined.

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 describes return format (paired data + citation URIs). Covers what data is returned for each type, making it complete enough for selection and invocation.

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

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

Schema already describes parameters with 100% coverage. Description adds context: type determines data source and fields, values specify examples like tickers or drug names and constraints (2–5 items).

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 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call,' with specific verb (compare) and resources (companies/drugs). Distinguishes from siblings by emphasizing efficiency over sequential lookups.

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

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

Explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides example queries. Lacks explicit when-not-to-use, but context is clear.

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

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

Beyond annotations (readOnlyHint, openWorldHint, etc.), the description discloses that it is not open-web search, returns gaps for unanswered facets, never invents, and expects 15-60s. No contradictions with annotations.

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

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

The description is comprehensive but well-structured, with critical info (account, alternatives) front-loaded. While long, every sentence adds value without redundancy.

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

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

Given the tool's complexity, many siblings, and lack of output schema, the description fully explains purpose, usage, constraints, and expected behavior, making it self-contained for an agent.

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

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

Schema coverage is 100%; both parameters have descriptions. The description adds minor context (e.g., depth maps to facets, question can be broad), but adds little beyond what the schema provides.

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

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

The description clearly states the tool performs multi-source research over structured data, decomposes questions into facets, and returns a findings packet. It distinguishes from siblings by contrasting with ask_pipeworx for single lookups and current news.

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

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

Explicitly states when to use (broad/multi-part questions over structured data) and when not (use ask_pipeworx for single lookup or breaking/current news). Also mentions account requirement and the need for a paid plan on 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 provide readOnlyHint=true, idempotentHint=true. The description adds that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly'. This enhances understanding of behavior beyond annotations.

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

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

The description is somewhat lengthy but front-loads the core purpose. Every sentence adds value: usage guidance, domain examples, output details. Could be slightly trimmed but remains effective.

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

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

Given the high schema coverage and rich annotations, the description provides complete context: what it does, when to use it, what it returns, and how to call it. There is no output schema, but the description clearly states the output format.

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 every parameter is described. The description further adds examples of valid queries (e.g., 'analyze housing market trends') and lists aliases, which helps agents understand the expected format 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?

The description uses specific verbs like 'find', 'browse', 'search', and identifies distinct resources (e.g., SEC filings, FDA drugs). It distinguishes this tool from siblings by noting it returns tool schemas ready to call and should be used first to see the option set.

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 'Call this FIRST when you have many tools available and want to see the option set'. It provides a comprehensive list of example domains but does not explicitly state when not to use it. However, the context makes usage clear.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral details: fans across multiple sources, returns specific fields (cik, filings, fundamentals, patents, news, LEI), and warns about patent API sunset. 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 a single detailed paragraph, front-loaded with example queries. It is somewhat long but every sentence adds value. Could benefit from slight structuring for readability, but remains 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 (multiple sources, no output schema), the description fully explains what is returned: cik, company_name, recent_filings with URIs, fundamentals, patents (with caveat), news, and LEI. It covers input constraints, source interactions, and fallback behavior.

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

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

Schema has 100% description coverage for both params. The description adds meaning by specifying acceptable values (ticker or zero-padded CIK), giving examples, and stating that names are not supported, which is not in the schema alone.

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

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

The description clearly states the tool returns a full cross-source profile of a US public company, with example queries like 'tell me about X' and 'company profile for Microsoft'. It distinguishes from siblings like resolve_entity by specifying that names are not supported and that this tool should be preferred over chaining individual lookups.

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

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

Explicitly tells when to use: for holistic views of US public companies, and when not: if only a name is available, use resolve_entity first. Also mentions that PatentsView API may soft-fail after May 2025, setting expectations.

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 usage context but does not disclose additional behavioral traits like irreversibility. Acceptable given annotation coverage.

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 short sentences, each with clear purpose: purpose, usage guidance, sibling pairing. No unnecessary words.

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

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

Adequate for a simple 1-param tool with full schema and annotations. Explains deletion purpose and usage contexts. No output schema needed for this operation.

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 the single parameter 'key' with description. The description adds no further meaning beyond 'by key'. Baseline of 3 is appropriate.

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

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

Description uses specific verb 'Delete' and resource 'previously stored memory by key'. Clearly distinguishes from sibling tools 'remember' (store) and 'recall' (retrieve).

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: context stale, task done, or clear sensitive data. Suggests pairing with remember and recall. Lacks explicit when-not scenarios, but 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, indicating safe, non-destructive behavior. The description adds process details (fetches page, extracts title/description/key links, emits standard format), which are consistent with annotations and provide useful context without contradiction.

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

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

The description is three tightly written sentences with a bulleted list of use cases. Every sentence serves a purpose: stating the goal, explaining the process, and listing applications. No fluff or redundancy.

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

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

Given 100% schema coverage, no output schema, and simple parameters, the description covers all necessary context: what the tool does, how it works, output format, and use cases. It is complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description's mention of 'fetches the page' and 'max 50 links' adds minimal extra meaning beyond the schema. Baseline 3 is appropriate as the description does not significantly enhance parameter understanding.

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

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

The description clearly states it generates an llms.txt file for any URL, targeting AI crawlers. It distinguishes from sibling tools like ai_visibility_check by specifying the output format and use cases, such as drafting llms.txt or auditing a competitor's site.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context for when to use it. It does not list alternatives or when not to use it, but the guidance is sufficient.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows it's safe. The description adds 'Higher quota cost per call', which is behavioral info beyond annotations. No contradictions.

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

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

Two sentences with no wasted words. The key purpose and a notable characteristic (cost) are front-loaded.

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

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

Given the output schema exists and annotations cover safety and idempotency, the description is mostly sufficient. However, it could briefly note the response structure or that odds are live, but it's not a critical gap.

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

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

Schema coverage is only 20%, meaning 4 out of 5 parameters are not described in the schema. The description does not elaborate on parameters like 'markets', 'regions', or 'odds_format'. It only mentions richer markets indirectly, which is insufficient to guide correct parameter usage.

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

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

The description clearly states 'Odds for a single event' and mentions 'richer markets (player props, alt lines)', which distinguishes it from sibling tools like get_odds that likely cover standard markets. The verb 'get' and resource 'odds' 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?

It indicates when to use (for richer markets) and notes higher quota cost, implying a trade-off. However, it does not explicitly state when not to use or name alternatives like get_odds, though the context of sibling tools provides that.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description need not repeat that. The description adds value by specifying that events are upcoming and live only, and that odds are excluded. It does not contradict annotations and provides additional 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, well-structured sentence of 9 words. It is front-loaded with key information and contains no filler. 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?

The description is fairly complete given the presence of an output schema (so return values are documented elsewhere). It covers the scope (upcoming+live), the exclusion of odds, and the use case. Minor gap: it does not explicitly state that sport_key is required or how the parameters map, 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 description coverage is 0% (no parameter descriptions). The description mentions 'for a league' (implying sport_key) and 'discover event IDs' (implying output includes IDs), but does not explain the event_ids or date_format parameters. It adds some meaning but insufficient for all three parameters.

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

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

The description clearly states the tool returns 'upcoming + live events for a league' and specifies it is 'without odds — useful to discover event IDs'. This distinguishes it from sibling tools like get_event_odds (which includes odds) and get_scores (likely past events). The verb and resource are clear.

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: 'without odds' suggests not to use when odds are needed, and 'useful to discover event IDs' hints at using this to get IDs for other tools. However, it does not explicitly state when not to use it or name alternative tools, which would be stronger guidance.

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

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

Annotations already declare read-only and idempotent behavior. The description adds valuable context about quota credit costs per market/region, which is not covered by annotations. This provides transparency on a behavioral constraint that affects tool usage.

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 precisely state the tool's purpose and a critical usage constraint. No superfluous information. 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 rich annotations, full schema coverage, and presence of an output schema, the description is nearly complete. It could mention that 'sport_key' is required, but that is already in the schema. The cost hint adds needed context for a tool with quota limitations.

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 full descriptions. The description adds extra meaning by linking markets and regions parameters to quota cost, advising careful selection. This enriches the parameter semantics 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 it provides 'current odds for upcoming + live events in a league,' using a specific verb ('get') and resource ('odds'). It distinguishes from sibling 'get_event_odds' by specifying a league scope rather than individual events.

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 usage hint about quota cost ('pick markets carefully'), which is helpful but does not explicitly guide when to use this tool versus alternatives like 'get_event_odds' or 'get_scores'. No explicit when-not or alternative naming is provided.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint (false). The description adds the specific behavioral trait 'Costs 2 requests per call', which provides rate-limit context beyond annotations. No contradiction exists.

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 with two clear statements. Every word serves a purpose: identifying the data type and a cost constraint. 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 presence of an output schema, return values are covered. The description explains purpose and a behavioral constraint (cost). However, it lacks context about the scope of scores (e.g., which sports, time range) and how to use the tool effectively. Adequate but not rich.

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 2 parameters with 50% description coverage (only 'days_from' described). The description does not mention any parameters or their roles, missing the chance to clarify meaning for 'sport_key' and usage of 'days_from'. Hence, the description adds no semantic value beyond the schema.

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

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

The description clearly states 'Live + recent final scores', using a specific verb and resource. It distinguishes from siblings like get_events and get_odds, which focus on different data. However, it does not explicitly differentiate from other score-related tools, hence not a 5.

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 lacks any guidance on when to use this tool versus alternatives. It only mentions a cost of 2 requests per call, which is a constraint but not usage context. No exclusions or prerequisites are stated.

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

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

Annotations already declare readOnly and idempotent. The description adds value by specifying that by default it returns only in-season sports and that all=true includes out-of-season. This is 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 sentences, front-loaded with the main action, no fluff. Each sentence provides essential information.

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

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

Given the simple tool with one parameter and an output schema, the description is complete. It explains the default and optional behavior, and the output schema handles 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 coverage is 100%, so the parameter is fully described in the schema. The description adds some context (in-season vs out-of-season) but essentially restates the schema's default false behavior. 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 'List available sports/leagues' with a specific verb and resource. It distinguishes this tool from sibling tools (e.g., get_events, get_scores) by clarifying it lists sports categories, not events or scores.

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

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

The description explains the default behavior (only in-season) and how to modify it (all=true), guiding when to use the parameter. It does not explicitly list alternatives or when-not to use, but the purpose is clear enough given sibling context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds value by listing specific fields returned and the implication of the include_inactive parameter, but does not elaborate on potential behavioral nuances like rate limits or pagination.

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

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

Two concise sentences that front-load the purpose and end with a usage prompt. No unnecessary words.

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

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

For a simple tool with one optional parameter and no output schema, the description adequately covers what the tool does, what it returns, and why to use it. No gaps identified.

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

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

Schema coverage is 100% with a clear description for the single parameter. The tool description does not add additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

Clearly states it lists the caller's active subscriptions and specifies returned fields. However, it does not explicitly distinguish itself from sibling tools like subscribe or unsubscribe, but the name and description make the purpose evident.

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

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

Provides explicit guidance on when to use: to review monitoring before adding more or to find an id to cancel. Does not mention when not to use or alternatives, but the context is clear.

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

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

The description discloses several behavioral traits beyond the annotations, such as that the team reads digests daily, feedback affects roadmap, rate limits apply, and the tool is free with no quota impact. There is no contradiction with the provided 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 and well-structured, using clear, purposeful sentences. It front-loads the key action and provides necessary details without redundancy or extraneous text.

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

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

Given the absence of an output schema, the description adequately covers all relevant aspects: when to use, how to provide feedback, constraints (rate limiting, quota), and expected input format. It is complete for a feedback submission 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?

Although schema coverage is 100%, the description adds semantic value by clarifying the enum values for 'type', providing examples for the optional 'context' object (e.g., pack slug 'fred'), and indicating the expected format for the 'message' field. This enriches the parameter understanding 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's purpose: to tell the Pipeworx team about bugs, missing features, or praise. It explicitly enumerates the use cases (bug, feature/data_gap, praise) and distinguishes this tool from its siblings, which are primarily data retrieval and research 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 provides explicit guidance on when to use the tool—for bugs, feature requests, data gaps, and praise. It also instructs what not to do (paste end-user prompts) and includes rate limit information (5 per day), helping the agent decide when to invoke this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that data is self-aggregating, derived from CF analytics-engine, no PII, and cached for 5 minutes to 1 hour. This provides useful behavioral context beyond annotations.

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

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

The description is concise (3 sentences) and well-structured: it states the purpose, lists use cases, and explains data source and caching. Every sentence adds value without redundancy.

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

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

Given the single parameter, no output schema, and comprehensive annotations, the description fully covers input, output (top tools/packs/volume), use cases, data source, and caching behavior. It is complete for the tool's simplicity.

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

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

Schema coverage is 100% with a description for the only parameter 'window'. The description adds semantics by explaining the trade-off between shorter and longer windows for surfacing hot vs. steady-state demand, which goes beyond the enum values.

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

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

The description clearly states what the tool does: returns top tools, packs, and call volume from other agents' calls to Pipeworx. The verb 'returns' and resource description are specific and distinguish it from sibling tools like 'ask_pipeworx' or 'discover_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?

Three specific use cases are listed (discovering hot data sources, confirming canonical tools, checking alignment), and the window parameter's effect is explained (shorter windows for hot, longer for steady-state). However, it does not explicitly state when not to use the tool or mention alternatives.

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

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

The description discloses detailed internal behavior including monotonicity violations, partition-sum checks, Jaccard similarity filtering, placeholder filtering, and fill checks against CLOB depth. Annotations already indicate idempotent and read-only, and the description adds rich behavioral context beyond that.

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, front-loading the main purpose and modes. Every sentence adds value, though minor trimming could improve conciseness without losing clarity.

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

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

Given the tool's complexity (multiple modes, internal checks, response structure), the description is comprehensive. It explains the output format including opportunities, partition_check, and fill_check, compensating for the lack of an output schema.

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

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

Schema coverage is 100%, but the description adds extensive meaning: it explains the mode triggered by each parameter, provides example values, and describes how the parameter affects the scan (e.g., event slug, seed question). This goes far beyond the basic 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between event and topic modes, and explains how each works, differentiating it from sibling 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?

Explicit guidance is given: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also recommends event mode for specific markets and mentions when to use polymarket_fill_risk for custom sizing, providing clear contextual alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds caching behavior (1h KV keyed on all knobs), Fed bets exclusion with rationale, and diagnostics for empty segments. 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?

Description is lengthy (several paragraphs) but structured with clear segments, knobs, and response fields. Front-loads purpose but contains technical details that could be condensed. Adequate but not maximally concise.

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

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

Given 9 parameters, no output schema, and high complexity, the description is remarkably complete. Covers model families, response structure, diagnostics, caching, Fed exclusion, tradeable-edge knobs, and empty-segment reasons. No obvious gaps.

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

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

Schema coverage is 100% with all 9 parameters documented. Description adds extra context for key parameters like min_partition_leg_kelly (explaining why min_kelly doesn't filter partitions) and slippage_pp (Polymarket fee context). Not every parameter gains new meaning, but the added detail 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?

Clearly states it scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price. Built for 'what should I bet on today' and distinguishes from siblings like polymarket_arbitrage and polymarket_kalshi_spread by focusing on edge scanning with three model families.

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

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

Implied usage for discovering betting opportunities without paging hundreds of markets. Provides context on when to use (discovery) but lacks explicit exclusions or alternatives. Guides usage via tradeable-edge knobs but does not say when not to use.

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

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

The description adds significant behavioral detail beyond the annotations (readOnly, openWorld, idempotent, non-destructive). It explains the output structure (tracked, expired, snapshot_dates), data sources (daily snapshots, cache-miss triggers), and computational details (decay computed on absolute edge, signed values). 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 lengthy but well-organized, front-loading the core purpose. It packs dense information without unnecessary fluff. However, it could benefit from bullet points or clearer section breaks for readability.

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 lack of an output schema, the description fully documents the response format, including the tracked, expired, and snapshot_dates arrays with their fields. It also covers limits (TTL, snapshot start time, decay granularity), making the tool's capabilities and constraints completely clear.

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 description enhances the schema (100% coverage) by providing defaults ('14' for days, '1wk' for window), constraints (max 30 for days), and context (what 'window' represents as a snapshot family). This adds meaning beyond the schema's property descriptions.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It uses specific verbs ('answers how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like `polymarket_edges` by focusing on temporal dynamics rather than current edges.

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

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

The description gives explicit guidance on when to use the tool: for understanding edge persistence over time and differentiating fresh vs. old wide edges. It mentions limits (60-day TTL, closes vs. intraday) but does not explicitly name alternative tools for other use cases, though the contrast with `polymarket_edges` is implicit.

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

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

The description goes well beyond annotations (which already indicate safe, read-only behavior) by detailing the internal process: 'walks the ladder and returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and a verdict.' It also discloses key behavioral traits like the risk of partial fills and uncapturable overround on thin books. 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 longer than average but well-structured with clear sections (SINGLE-MARKET, BASKET) and all-caps key terms. Every sentence adds value—no filler. While slightly verbose, it remains effective and front-loaded.

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

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

Despite lacking an output schema, the description thoroughly enumerates all return values for both modes (e.g., 'theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk'). It also explains risks and edge cases, making it self-sufficient for an AI agent to understand consequences.

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

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

Schema coverage is 100%, providing baseline 3. The description adds substantial meaning by explaining the mutual exclusivity of 'market' and 'event', the interpretation of 'side' and 'size_usd' in each mode, and the auto-detection of side in basket mode. This extra context raises the score to 4.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use this tool before them.

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

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

The description provides explicit usage guidelines: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (partial basket fills convert arb into unhedged directional position), offering clear when-to-use and when-not-to-use context.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds extensive behavioral context: two modes, response fields (spread, compatibility_warning, temporal_alignment, skipped counters), conditions for warnings (matched_pairs:0 cases), and explanations of temporal alignment and skipped cross-type/cross-subtype. This far exceeds what annotations provide.

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

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

The description is long but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). It is dense with important details for a complex tool. Some redundancy exists (the last sentence on pre-mapped topics restates earlier caution), but overall it is efficient for the complexity. Could be slightly 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?

Even without an output schema, the description explains the response structure: each venue's leg-by-leg prices, matched spread top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. It covers edge cases (compatibility_warning conditions, temporal misalignment). For a tool with 3 optional parameters, no nested objects, and no output schema, the description is complete.

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

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

Schema coverage is 100%, meaning all three parameters are documented in the schema. The description adds significant meaning beyond schema: it explains the two modes (topic auto-fetches vs explicit overrides) and gives examples. It clarifies that topic is a pre-mapped shortcut and that kalshi_event_ticker/polymarket_event_slug override the mapped side. This adds value.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts vs explicit tickers) and explains that pre-mapped topics may not always be tradeable due to compatibility issues. The verb 'compute spread' + specific resource + mode differentiation makes the purpose very clear.

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

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

The description explains when to use this tool (to compare prices across prediction markets for the same event) and when not to use it (most pre-mapped topics return compatibility_warning, so real spreads are rare). It provides explicit context for the two modes and the safety fields that indicate when the tool's output is meaningful. Although alternative tools are not mentioned, the guidance is clear and sufficient.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds scoping (identifier-based) and pairing with remember/forget, providing useful context beyond annotations.

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

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

Three concise sentences with no wasted words; the core action is front-loaded, and each sentence adds distinct value (action, use case, scoping/pairing).

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

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

For a single optional parameter tool with full annotation coverage and no output schema, the description comprehensively covers behavior, usage, scoping, and relationships to 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 coverage is 100% with a clear property description. The description adds minimal new info beyond repeating the schema's 'omit to list all keys' behavior, so baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves a saved value or lists all keys, using specific verbs ('Retrieve'/'list') and resource ('memory'), and distinguishes from sibling tools 'remember' and 'forget'.

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

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

The description explains when to use (look up stored context) and when to omit the key (list all), but lacks explicit when-not-to-use guidance or alternative tool names.

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

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

Adds behavioral details beyond annotations: describes returned fields (source, citation_uri, raw payload) and explains that mark_read:true affects subsequent calls. 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?

Information-dense single paragraph that front-loads purpose. Every sentence adds value, but could be slightly more structured for readability.

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 rich annotations and full schema coverage, the description completes the picture by specifying return value contents, polling suitability, and alternative access. No output schema needed.

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

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

Schema coverage is 100% but description adds value with examples (e.g., 'sec_8k' for type) and clarifies behavior of mark_read. Exceeds 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?

Clearly states it pulls fired events from a subscription feed and returns recent alerts. Uses specific verbs and resource, and implicitly distinguishes from siblings like 'get_events' and 'list_subscriptions'.

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

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

Provides explicit guidance on filtering by type and since, and setting mark_read. Mentions polling and alternative HTTP endpoint, giving context for when to use this tool vs direct API access.

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, etc. The description adds significant behavioral context: fan-out to multiple sources, fallback from GDELT to GNews, soft-fail for USPTO, and the return structure including 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 comprehensive but somewhat verbose, including many query examples that could be condensed. It is front-loaded with examples but contains some redundancy. It earns its place but 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 complexity (multiple sources, fallback, parameter options) and no output schema, the description fully covers behavior, parameters, return structure, and provides an alternative tool. It is complete for agent usage.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'since' parameter with both ISO and relative shorthand examples, and clarifying 'value' accepts ticker or CIK. This goes beyond the schema but doesn't drastically change understanding.

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

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

The description clearly states the tool returns a change feed for a company over a specified window, fanning out to SEC, GDELT/GNews, and USPTO. It uses specific verbs and resources, and explicitly distinguishes from sibling entity_profile, achieving high purpose clarity.

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

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

The description provides explicit usage examples and a clear alternative (entity_profile for static profiles). It does not exhaustively list all sibling tools but gives sufficient guidance on when to use this tool versus a key alternative.

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

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

Annotations already indicate idempotentHint=true and not read-only or destructive. The description adds valuable context beyond annotations: scoping by identifier, persistence duration (24 hours for anonymous, persistent for authenticated), and pairing with recall/forget. 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 three sentences, front-loading the primary action and providing necessary context in an efficient manner. Every sentence serves a purpose: stating the action, usage context, and persistence details. No redundant or wasted text.

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

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

Given the tool has 2 parameters, no output schema, and annotations providing safety signals, the description is reasonably complete. It covers purpose, usage, persistence, and pairing. However, it could mention whether overwriting an existing key is allowed (implied by idempotentHint) and any value length limits, but these are minor gaps.

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

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

Schema coverage is 100% with clear descriptions for both key and value parameters. The description does not add significant meaning beyond the schema; it restates that data is saved as key-value pairs. Baseline score of 3 is appropriate as the schema carries the informational load.

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

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

The description clearly states the purpose: 'Save data the agent will need to reuse later' with a specific verb (save) and resource (data as key-value pairs). It distinguishes itself from siblings by mentioning recall and forget as paired tools, which are present in the sibling list.

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: 'when you discover something worth carrying forward... so you don't have to look it up again.' It also explains persistence behavior and mentions alternatives (recall, forget). It doesn't explicitly state when not to use, but the context is clear enough for appropriate selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds valuable context: internal cascading through several lookup endpoints and auto-disambiguation for company inputs. 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 well-structured with examples, purpose, supported types, and a behavioral note. At about 100 words, it is efficient but could be slightly more compact. However, every sentence adds value.

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

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

Given there is no output schema, the description compensates by explaining what each entity type returns (including citation URIs). It covers the full purpose, usage scenario, and result details, 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 description adds significant meaning: for company, it lists returned fields (ticker, CIK, company_name, citation URI) and accepted input formats (ticker, CIK, name). For drug, it lists RxCUI, ingredient, brand, citation URI, and input examples. This goes well beyond the schema's brief descriptions.

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

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

Description starts with concrete example queries and clearly states the tool resolves names to canonical identifiers required by other tools. It specifies supported entity types (company, drug) and what each returns. This distinguishes it from sibling tools like entity_profile or compare_entities.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID,' providing strong positive guidance. It also notes that using resolve_entity replaces 2-3 manual lookups, emphasizing efficiency. Could improve by explicitly stating when not to use it, but the context is clear.

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

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

Annotations already cover safety traits (readOnly, idempotent, non-destructive). The description adds behavioral details: it calls ai_visibility_check internally, ranks results, and returns a ranked list with score, confidence, and signal density. This goes beyond annotations to clarify execution flow.

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 (4 sentences), front-loaded with the core purpose, and every sentence adds value. No redundant or filler content.

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

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

Given the absence of an output schema, the description adequately describes the return format (ranked list with score, confidence, signal density). It also mentions internal tool usage. The only minor gap is not explicitly restating the entity count constraint (2-8), but that is covered in the schema.

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

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

Input schema has 100% coverage, so all parameters have descriptions. The description adds value by noting that the first entity is treated as the 'subject' for narrative purposes, which is not in the schema. This extra context aids understanding of parameter semantics.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and identifies most/least recognized. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (generic) by focusing on competitive AI-marketing audits.

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

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

The description provides clear usage context: 'Useful for competitive AI-marketing audits' with an example. However, it does not explicitly mention when not to use or directly name alternatives like ai_visibility_check for single entities, leaving some room for inference.

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, open-world, non-destructive. Description adds significant behavioral detail: partial failures degrade gracefully, bundlephobia first measurement may take 5-30s, sources_failed field lists timeout failures. This goes beyond annotations.

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

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

Description is moderately concise, packing much information in a single paragraph. Could benefit from line breaks for readability, but it front-loads the purpose and is efficient. Each sentence adds value.

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

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

Despite no output schema, the description thoroughly covers return values: summary block, per-advisory detail, links, alternative versions. Also covers failure modes and ecosystem limits. Complete for a complex composite 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 has 100% description coverage for both parameters. Description adds value by noting that scoped packages (e.g. @types/node) are accepted and version defaults to latest when omitted. This extra context justifies a score above 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?

The description clearly states the composite purpose: a one-call check for adding an npm package, covering safety, popularity, and size via deps.dev and bundlephobia. It is specific and distinct from sibling tools (mostly sports/bet related).

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

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

Explicitly states when to use: when an agent asks about safety/popularity/size or cost of adding a package. Also provides exclusion guidance: NPM only in v1, other ecosystems fall under different tool (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?

The description adds significant behavioral context beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It details the embedding model (BGE-base-en), similarity metric (cosine), windowing strategy (500-char overlapping windows), and the 200K char cap with truncation flagging. 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 a single well-structured paragraph. It front-loads the purpose, then provides usage guidelines, and ends with technical details. Every sentence earns its place; no redundant or filler content.

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

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

Given no output schema, the description adequately explains what is returned (top-N passages with character offsets and similarity scores). It covers input constraints, pairwise usage with another tool, and behavioral details. For a tool with 3 parameters and no output schema, this is comprehensive.

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% (all parameters have descriptions). The description adds value by providing example queries for the 'query' parameter and clarifying the nature of the 'text' parameter as document text with a maximum size. It does not repeat schema info but enriches it with usage examples.

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 performs semantic search inside a fetched record, with specific examples like SEC 10-K, article, or tool result. It distinguishes itself from siblings by mentioning pairing with ask_pipeworx_grounded and explaining the output (top-N passages with character offsets and similarity scores).

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

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

The description explicitly states when to use this tool: when the record is too big to cram into the prompt. It also provides context about saving context and returning only relevant passages. However, it does not explicitly mention when not to use it or list alternative tools beyond the pairing hint.

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=false and destructiveHint=false. Description adds that subscriptions persist, requires auth, returns a new ID, and details delivery channel behavior including SMS cap and webhook signing. Consistent 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 with sections for purpose, requirements, supported types, and delivery channels. Front-loaded with core action. Some redundancy (e.g., delivery details repeated in schema) 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 return value, account prerequisites, type parameters, delivery options, and limitations. Lacks error scenarios or idempotency details. Still sufficient for 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%, so baseline is 3. Description adds significant value by explaining type-specific parameters (e.g., items codes for sec_8k, topics for polymarket_edge) and delivery channel options with constraints.

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 'Create a proactive monitoring subscription' with specific verb and resource. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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?

Specifies requirement for Pipeworx OAuth account and lists supported types with examples. Provides limitations (BYO/anonymous not allowed, SMS cap). However, no explicit when-not-to-use or alternative tool comparisons.

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 value by explaining the output format (category-bucketed questions with tool+argument shapes) and behavior with/without the topic argument. 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 well-structured and front-loaded with purpose and usage. It is slightly verbose due to exhaustive category listing, but every sentence adds value. 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?

Given no output schema, the description explains what the tool returns (category-bucketed example questions with exact tool + argument shape). It covers input semantics fully and provides sufficient context for an onboarding tool. No missing details needed.

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

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

Schema coverage is 100% with one optional parameter (topic). The description adds meaning by listing the categories, explaining behavior with and without the argument, and clarifying the purpose of focusing the output. This goes 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 returns category-bucketed example questions for what Pipeworx can do. It specifies the resource (example questions) and verb (suggest/return), and distinguishes itself from siblings by positioning as the onboarding entry point.

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

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

The description explicitly says to use this tool FIRST when unsure what Pipeworx can do, and to learn how to call meta-tools. It also mentions optional topic filtering. However, it does not explicitly state when not to use it, though 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?

Disclosures behavioral nuance beyond annotations: 'row is deactivated (not deleted) so historical events stay available via recent_alerts'. Annotations already indicate non-destructive, but description adds clarity on deactivation vs deletion.

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 covering all key points with zero waste. Each sentence adds essential information: purpose, ownership, and effect.

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 one-param tool with no output schema, the description is fully adequate. It explains input, effect, ownership, and ties to sibling 'recent_alerts'. Context signals confirm no missing details.

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 schema description already explains 'id' as 'Subscription id (uuid) returned by subscribe.' Description adds minimal value beyond rephrasing 'by id'. 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 verb 'Cancel' and resource 'subscription by id'. Distinguishes from sibling 'subscribe' and implies action opposite to subscribe.

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 ownership enforcement guideline: 'you can only cancel your own subscriptions'. Does not mention when-not-to-use explicitly but implies limitations. Lacks alternatives, but context signals provide siblings like 'list_subscriptions'.

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

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

Annotations already provide safety hints (readOnly, idempotent, non-destructive). The description adds behavioral details: returns a verdict, extracted form, actual value with citation, percent delta, and underlying data sources (SEC EDGAR + XBRL). No contradiction with annotations.

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

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

The description is dense but well-structured. It starts with example queries, states purpose, scope, returns, and value proposition. While slightly long, every sentence adds useful 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 has only one parameter and no output schema, the description is comprehensive. It explains return types (verdict categories, citation) and the broader context (replaces multiple calls), making it fully self-contained.

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

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

Schema coverage is 100% with one parameter (claim). The description adds meaningful context beyond the schema by providing example claims and explaining the natural-language format, which helps the agent construct valid inputs.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It specifies the domain (company-financial claims for public US companies) and distinguishes it from sibling tools by noting it replaces 4-6 sequential calls.

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

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

The description explicitly says when to use ('whenever the agent needs to check whether something a user said is factually correct') and what types of claims (company-financial). It doesn't explicitly say when NOT to use, but the domain restriction implies limitations.

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