Statbank Md

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds crucial behavioral details: default model (Workers AI), cost model for Anthropic (BYO key), and return format (per-model {score, confidence, signals, raw_response} + combined view). 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, front-loaded with purpose, then details. Every sentence adds information without redundancy. Highly 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?

Despite no output schema, the description explains the return format and lists all parameters with usage notes. Annotations cover safety. The tool is a probe/query with clear inputs and outputs. Complete for the task.

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

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

Schema covers all 4 parameters with descriptions (100% coverage). The description adds value by explaining defaults (models: Workers AI if omitted), the BYO key concept for _apiKey, and the disambiguation purpose of context. Goes beyond schema.

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

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

The description clearly states the tool's purpose: probing LLMs about an entity and scoring visibility, with specific verb 'probe', resource 'LLMs', and outcome 'score (0-100)'. It distinguishes from siblings by focusing on AI visibility rather than other tasks like betting or entity comparison.

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

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

The description provides use cases (AI-marketing audits, pre-launch brand checks) and explains when to use Anthropic (with API key). It does not explicitly state when not to use or alternatives among siblings, but the context is sufficient.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. Description adds crucial behavior: routes to 3,272 tools, fills arguments, returns structured answers with citation URIs. No contradictions.

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

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

Single paragraph, front-loaded with key preference, but somewhat long. Contains examples and extensive domain list. Could be trimmed without losing meaning, but structure is logical.

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

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

Given no output schema, description adequately covers input format, routing behavior, and return type (structured answer with URIs). Examples illustrate usage. Slightly more detail on output structure would improve completeness.

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

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

Schema coverage is 100% with all parameters described as aliases for 'question'. Description adds value by explaining the nature of the question (natural language, examples) and providing typical use cases beyond the schema's description.

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

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

Description clearly states the tool's purpose: answering questions about current/historical data from reputable sources. It explicitly prefers over web search and lists many domains (SEC filings, FDA data, etc.), distinguishing 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?

Provides explicit guidance on when to use: for factual queries like 'what is', 'look up', 'find', etc. States preference over web search and gives examples. Lacks explicit when-not-to-use instructions but the positive guidance is strong.

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

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

Annotations declare readOnlyHint, destructiveHint=false, idempotentHint. The description adds extensive behavioral details: fan-out to category-specific data packs, resolution process, classification, response shapes, edge cases (low-confidence short-circuits, closed markets skipped, wide-spread warnings), resolver contract, parent event extractor, news fallback fields. No contradictions.

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

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

The description is quite long but well-structured with clear sections (classifiers, fan-out examples, response shapes, safety notes). It is front-loaded with the main purpose and usage. Some redundancy exists (e.g., repeated mention of low-confidence paths), but given the tool's complexity, the length is justified.

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

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

Despite no output schema, the description thoroughly explains response shapes (result.market, result.analysis, result.evidence), fields, and edge cases (resolver confidence, parent event extraction, news fallback, liquidity warnings). It covers all necessary context for an agent to correctly interpret and act on the tool's output.

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

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

Schema coverage is 100%, and the description enriches each parameter: market input format (slug, URL, question text), depth enum ('quick' vs 'thorough' with default), include_raw boolean with clear effect on response size. Examples illustrate 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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the action (research), resource (Polymarket bet), and method (pulling Pipeworx data). It distinguishes from sibling tools like pipeworx_trending or polymarket_edges by positioning itself as a comprehensive research tool.

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

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

The description explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides when-not-to-use examples through safety notes (low-confidence, closed markets) and mentions alternative fields like parent_event for elections/championships, guiding appropriate usage.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds rich behavioral details: for companies, it pulls from SEC EDGAR/XBRL (latest 10-K), mentions a fix for correct fiscal year data, and notes off-calendar handling. For drugs, it pulls from FAERS/FDA. It also returns citation URIs and sorts 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?

Description is well-structured with a clear front-loaded purpose. Each sentence adds relevant information without redundancy. Though it is somewhat lengthy, it is efficient for the complexity of the tool. Minor excess could be trimmed, but overall it is well-written.

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, description adequately explains return format: paired data with citation URIs and sorted results. All 2 params are fully described (100% schema coverage). The description provides sufficient context for an agent to use the tool correctly without missing important 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 has 2 params with 100% description coverage. Description adds value by providing concrete examples for the 'values' parameter (e.g., tickers for company, drug names) and explaining sorting behavior. This goes beyond the schema descriptions.

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

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

Description clearly states verb 'compare', resource 'entities' (companies or drugs), and scope '2-5'. It distinguishes between two entity types and provides concrete use cases like 'compare X and Y', 'X vs Y', etc. It also mentions it replaces 8-15 sequential lookups, making its purpose very 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?

The description explicitly lists when to use the tool: for comparison, ranking, or metric-based questions. It gives example queries. However, it does not explicitly mention when not to use it or list alternative tools among the 26 siblings. The context is strong but lacks exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining the return format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' No contradictions.

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

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

The description is concise—three sentences—with no wasted words. It front-loads the main purpose and adds domain examples and output behavior efficiently.

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

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

Despite no output schema, the description fully explains what the tool returns (top-N tools with schemas) and when to use it. No missing context for a discovery tool.

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

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

Schema coverage is 100% with all parameters described. The description does not add extra meaning beyond schema, but the schema itself is adequate. Baseline 3 is appropriate given high coverage.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and distinguishes itself from siblings as the discovery hub to find other 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 clear usage context: 'Use when you need to browse, search, look up, or discover what tools exist...' and 'Call this FIRST when you have many tools available.' It lacks explicit exclusion but offers strong guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds useful behavioral context: returns detailed fields, mentions known limitations (patents sunset, FY2025 numbers), and data sources. No contradictions.

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

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

Description is verbose with multiple sentences and technical details (e.g., 'Run 6 fix landed real FY2025 numbers'). While informative, it could be more streamlined for quick parsing. Still, all sentences add value.

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

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

No output schema, so description fully explains return structure: cik, company_name, recent_filings with URIs, fundamentals with specific fields, patents status, news fallback, LEI. Covers caveats and current limitations thoroughly.

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%. Description enhances both parameters: type only 'company' currently (future plans), value explains ticker/CIK formats and explicitly says names not supported. Adds context beyond schema.

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

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

Description clearly states 'Get everything about a US public company in one call.' It specifies the resource (US public company), the action (get), and differentiates from siblings by noting it replaces calling 10+ other tools like SEC EDGAR, XBRL, USPTO, etc.

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

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

Explicitly tells when to use (when user asks 'tell me about X', 'research Acme', etc.) and when not to use (names not supported, recommend resolve_entity instead). Provides clear alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description confirms deletion and adds context about clearing sensitive data, but does not elaborate on error behavior or side effects beyond what annotations convey.

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 front-load purpose and usage. Every sentence adds value, no wasted words.

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

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

For a simple one-parameter tool with annotations, the description covers purpose, usage, and pairing. Lacks details on return values or idempotency behavior, but no output schema exists to expect those.

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 of the single parameter 'key'. The description merely restates 'by key' without adding new meaning beyond the schema.

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

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

Clearly states verb 'Delete' and resource 'previously stored memory by key'. Distinguishes from siblings by explicitly mentioning 'remember' and 'recall' as paired tools.

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

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

Provides explicit when-to-use scenarios ('context is stale, the task is done, or you want to clear sensitive data') and mentions alternatives ('Pair with remember and recall').

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering safety and idempotency. Description adds that it fetches the page and emits a text blob, but lacks details on potential rate limits or content limitations. The bar is lowered due to 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-loaded with purpose, and every sentence adds value. 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 the tool's simplicity (2 params, no output schema needed), the description is complete. Annotations cover behavioral aspects, and the description explains output format and use cases adequately.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by specifying default (25) and max (50) for max_links, and clarifying URL format. This goes beyond the schema descriptions.

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

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

The description uses a specific verb 'generate' and resource 'llms.txt file for any URL', clearly distinguishing from sibling tools like 'scan_competitor_ai_presence'. It explicitly states the output and purpose for AI crawlers.

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

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

The description lists concrete use cases (getting client site indexed, drafting for own project, auditing competitor). It does not explicitly mention when not to use, but the context is sufficient. No alternative tool is named among siblings.

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

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

The description discloses important behavioral details: it is rate-limited to 5 per identifier per day, does not count against tool-call quota, and that feedback affects the roadmap. Annotations are all false, so no contradictions.

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

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

The description is well-structured and front-loaded with the purpose, followed by usage guidelines and constraints. Every sentence adds value, and there is no verbosity.

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

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

Given the tool's complexity (3 params, nested object, enum, no output schema), the description is thorough. It covers when to use, what to include, limitations, and how feedback is processed, leaving no gaps.

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

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

Schema coverage is 100% and parameter descriptions in the schema are already detailed. The description adds context for the 'type' enum but does not significantly enhance understanding of parameters 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's purpose: to provide feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It distinguishes from sibling tools by focusing on feedback, which none of the siblings offer.

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

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

The description explicitly specifies when to use the tool (for bugs, features, data gaps, praise), what not to do (don't paste end-user prompts), and includes rate limits and quota information. It provides clear guidance on usage.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: data is self-aggregating from CF analytics, no PII, cached 5min-1h. This exceeds annotation coverage 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?

Concise: three sentences, first sentence front-loads the core action, second lists use cases efficiently, third provides transparency on source and caching. No redundancy or filler.

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

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

Despite lacking an output schema, the description adequately explains return values (top tools, top packs, call volume) and provides source and caching info. All essential context for a read-only trend tool is present.

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

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

The schema covers the single parameter with 100% description (enum + description). The description adds meaning by contrasting short vs long windows ('surface what's hot right now' vs 'steady-state demand'), providing behavioral context beyond the schema.

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

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

The description clearly states it returns top tools, packs, and call volume over a window. It distinguishes itself from siblings like discover_tools by focusing on what 'other AI agents are calling' right now, providing a specific verb+resource scope.

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

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

The description lists three explicit use cases (discovering hot data sources, confirming canonical choices, aligning use case with demand). It lacks explicit when-not-to-use guidance but provides strong contextual cues for appropriate usage.

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

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

Annotations indicate read-only, idempotent behavior. The description adds rich behavioral details: walking child markets, computing checks, applying thresholds (3pp, 0.30 similarity), and filtering partitions. It explains the logic behind arbitrage detection and what responses contain, going well beyond annotations.

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

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

The description is dense but well-organized, with clear separation of modes and key logic. It is front-loaded with the main purpose. Though lengthy, most sentences add value; minor improvement could be structuring with bullet points for easier scanning.

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 output schema and tool complexity, the description thoroughly covers modes, algorithms, thresholds, filters, and expected response fields (opportunities with gap_pp, suggested_trade, etc.). It provides enough context for an AI agent to use the tool correctly and interpret results.

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

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

Schema coverage is 100% with both parameters described. The description adds contextual meaning: explains that 'event' activates single-event mode and 'topic' cross-event mode, provides examples, and details the internal processing (search, flatten, comparator). This enhances understanding beyond the schema basics.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It outlines two distinct modes (event and topic) with specific use cases, distinguishing it from sibling tools like polymarket_edges.

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

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

The description provides explicit guidance on when to use each mode (event for single event, topic for cross-event search) and explains key filters like Jaccard similarity and partition placeholder filtering. However, it does not explicitly state when not to use this tool or mention alternatives among siblings.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: caching at KV level for 1 hour, three response segments with detailed model families, diagnostic fields, fed_note exclusion, and tradeable-edge filters. No contradictions.

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

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

The description is verbose but well-organized with clear segmentation (model families, knobs, response structure). Front-loaded with the main purpose. Minor redundancy (e.g., repeating filter explanations), but overall 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?

For a complex tool with 9 parameters, no output schema, and nested segments, the description is exceptionally complete. It explains all response fields (by_segment, diagnostics), caching behavior, fed_note exclusion, and knob usage. Leaves little ambiguity.

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

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

Schema description coverage is 100%, so baseline is 3. The description enhances understanding by explaining the purpose of each knob (e.g., min_liquidity, max_spread_pp) and how they affect edge realiability. It adds value beyond the schema's 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 scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price, and is built for 'what should I bet on today'. It distinguishes itself from siblings like polymarket_arbitrage by focusing on edge detection.

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

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

The description provides clear context: 'agents discover opportunities without paging hundreds of markets' and explains the tradeable-edge knobs. However, it does not explicitly compare to sibling tools like bet_research or polymarket_arbitrage, missing some direct exclusions.

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

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

Annotations already indicate readOnlyHint and idempotentHint. The description adds extensive behavioral context: response structure (leg-by-leg prices, spread arrays), safety fields (compatibility_warning conditions, temporal_alignment), and explains why spreads may be meaningless (e.g., non-equivalent bet shapes). No contradictions with annotations.

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

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

The description is well-structured: purpose first, then modes, response details, safety fields, and a final caveat. Every sentence adds information, though it is slightly lengthy; could potentially be trimmed 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?

Despite having no output schema, the description fully covers the response format, error conditions (compatibility_warning scenarios), temporal alignment, and skipped comparisons. It provides sufficient information for an agent to understand tool behavior and interpret results 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?

Input schema has 100% description coverage for 3 parameters. The description adds value by listing the exact topic shortcuts, explaining how explicit tickers override topic-mapped sides, and detailing response fields that are not in 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 identifies the tool as computing cross-venue spreads between Kalshi and Polymarket, specifies two modes (topic shortcuts and explicit tickers), and differentiates from sibling tools like 'polymarket_arbitrage' by detailing compatibility warnings and temporal alignment checks.

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

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

Provides explicit when-to-use guidance for both modes, warns that pre-mapped topics often yield compatibility warnings and are not necessarily tradeable, but does not name alternative sibling tools for comparison.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint. Description adds that it is a POST request with a PxWeb query object and a cell limit, adding behavioral context beyond annotations.

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

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

Two concise sentences front-load purpose and constraint. 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?

For a simple query tool with good schema and annotations, the description is mostly complete. It lacks details on error handling or return format, but schema covers json-stat2 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 covers both parameters fully with descriptions. The description adds context that body is a 'PxWeb query object' and constrains selected cells, enhancing understanding beyond the schema.

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

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

The description clearly states the tool pulls data from a table using POST, and specifies the query object format. It distinguishes from sibling 'table_meta' by implying data retrieval vs metadata, but does not explicitly differentiate.

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

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

The only usage guidance is to keep selected cells under 10,000. No explicit when-to-use or when-not-to-use instructions, and no reference to alternative tools.

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

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

Adds behavioral context beyond annotations: explains the dual mode (retrieve vs list), scoping, and pairing with remember/forget. No contradiction with readOnlyHint and destructiveHint.

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

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

Two sentences, no wasted words, front-loaded with the core action.

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

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

Covers purpose, usage, and scoping adequately for a simple retrieval tool; missing output description but no output schema exists to compensate.

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

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

Schema coverage is 100% and description reinforces that omitting key lists all keys, but does not add new semantic depth beyond schema.

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

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

Description clearly states the tool retrieves a saved value or lists all keys, distinguishing it from siblings like remember and forget.

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

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

Explicitly says when to use (look up stored context) and mentions scoping; does not explicitly state when not to use or name alternatives, but context is clear.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds rich behavioral context: parallel fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail, and return format. 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?

Every sentence adds value—purpose, use case examples, parallel source behavior, parameter details, return structure, and sibling guidance. No filler or repetition. Well-organized 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 no output schema, the description explains return format (structured changes grouped by source, total_changes count, citation URIs). It covers all behavioral nuances, parameter semantics, and provides an explicit alternative (entity_profile). Complete for a tool of this complexity.

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

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

Schema coverage is 100%, but the description adds value beyond enum/type definitions: explains that `since` accepts both ISO dates and relative shorthands with examples, recommends '30d' or '1m' for typical monitoring, and clarifies that `value` can be ticker or CIK. This helps the agent construct proper 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: 'What's new with a company in the last N days/months?' It lists specific use cases and explicitly distinguishes itself from the sibling tool entity_profile, which is for static profiles regardless of window.

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 (monitoring recent changes) and when to use entity_profile instead. It also details the parallel fan-out behavior and fallback logic, helping the agent choose appropriately.

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 non-read-only, idempotent, non-destructive. Description adds valuable context about persistence (authenticated vs anonymous, 24-hour retention) beyond annotations.

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

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

Three sentences front-load purpose, then usage, then retention details. No fluff, 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?

Even without an output schema, the description fully addresses purpose, usage, sibling relationships, and persistence scoping—complete for a simple key-value store.

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

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

Schema covers 100% of parameters with descriptions; the tool description only reinforces key-value pairs without adding new semantics, matching the baseline.

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

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

The description clearly states the tool saves data for reuse across sessions, specifies key-value storage, and explicitly names sibling tools (recall, forget) for differentiation.

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

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

Provides explicit when-to-use guidance (discover something worth carrying forward) and mentions alternative tools (recall, forget) with clear roles.

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

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

Annotations already mark readOnlyHint, idempotentHint, and openWorldHint. Description adds that each call cascades through several lookup endpoints, which is extra behavioral context. 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?

Four sentences with clear structure. Front-loaded purpose, then bullet-like SUPPORTED TYPES. No redundant 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?

Covers purpose, when to use, parameters, expected outputs (despite no output schema), and internal behavior. Sufficient for agent to correctly invoke.

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% coverage, baseline 3. Description adds crucial detail: for company, accepts ticker, CIK, or name with auto-disambiguation; for drug, accepts brand or generic. Also explains return fields (ticker, CIK, etc.). Adds significant value beyond schema.

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

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

Clearly states the tool resolves user-spoken names to canonical identifiers needed by other tools. Mentions specific types (company, drug) and distinguishes by providing example outputs and inputs.

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 agent to 'Use FIRST when you have a name but need an ID.' Also mentions it replaces manual lookups. Lacks explicit when-not-to-use but context is clear.

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

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

Annotations already mark it as read-only, idempotent, safe. The description adds behavioral details: probes each entity, ranks by score, surfaces most/least recognized, and returns score, confidence, signal density. No contradictions.

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

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

Two sentences, each earning its place: first defines action and mechanism, second provides context and a concrete example. No filler.

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

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

Given no output schema, the description fully explains what is returned (ranked list with score, confidence, signal density per entity) and includes an example scenario. Parameter count and schema coverage are adequate.

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

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

Schema has 100% coverage; the description adds key semantic insight: first entity treated as 'subject' for narrative, rest as competitors. This goes beyond the schema's per-parameter descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check per entity, and ranks results by score. It differentiates from sibling tools like ai_visibility_check (single entity) and compare_entities (generic) by specifying its competitive audit purpose.

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

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

Provides clear usage context: 'competitive AI-marketing audits' with an example. Implicitly advises use when comparing multiple entities, but does not explicitly state when not to use or alternatives (e.g., when to use ai_visibility_check alone). Still, the guidance is strong for the intended use case.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds transparency about partial failures: bundlephobia might time out but returns other data gracefully, with 'sources_failed' field.

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 comprehensive but slightly verbose; however, every sentence adds essential context. Front-loaded with the core purpose, and no redundancy.

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

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

Without an output schema, the description details all returned fields (summary block, advisories, links, alternatives). Also covers partial failure and ecosystem scope.

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

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

Schema has 100% coverage with descriptions. The description adds value by clarifying scoped packages format and default version behavior (latest).

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

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

The description clearly states it's a composite check combining deps.dev and bundlephobia data to answer 'should I add this npm package'. It specifies the exact purpose and distinguishes itself from sibling tools by being the only one performing this composite analysis.

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

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

Explicitly says when to use ('is X safe / popular / small') and when not to (other ecosystems like PyPI, Maven, etc. should use deps.dev:version directly). Also warns about potential delays for bundlephobia first measurement.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds behavioral context by explaining the tree navigation logic (e.g., empty path returns databases, drilling returns folders/tables), which goes beyond what annotations provide. However, it could mention error handling 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?

The description is concise with two sentences. It front-loads the purpose ('Navigate the database/subject tree') and packs details about behavior efficiently, with no wasted words.

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

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

Given the single parameter, no output schema, and rich annotations, the description is complete. It explains the tree structure and path semantics adequately for an agent to use the tool correctly.

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

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

With 100% schema coverage and one parameter 'path', the description adds significant meaning beyond the schema. It explains that an empty path lists databases and that the first segment is a database ID, and provides examples like '20 Populatia...'. This clarifies the navigation logic.

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: navigating a hierarchical database/subject tree. It specifies that the root path lists databases, and drilling into a database ID yields folders and tables with type indicators, distinguishing it from sibling tools like query_table or table_meta.

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

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

The description implies usage for exploration but does not explicitly state when to use this tool versus alternatives like query_table or table_meta. While it provides context on the tree structure, it lacks explicit guidance on selection criteria.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds that it returns dimensions and valid values, which is useful but minimal. It does not mention error handling or output format.

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

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

The description is very short at two lines, but the first line is a fragment. It is concise and to the point, though slightly awkward; still, it contains 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?

For a tool with one parameter and no output schema, the description is minimally adequate. It defines the return content and a path constraint, but lacks details on return format, error cases, and differentiation from similar 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?

The input schema has 100% coverage with a description for the 'path' parameter. The description adds a critical constraint that the path must end in '.px', which enhances understanding beyond the schema.

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

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

The description lacks a verb and reads as a noun phrase 'Table definition', making the action implicit. It does not distinguish this tool from siblings like 'query_table', which also deals with table data.

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

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

No guidance is given on when to use this tool versus alternatives. The only usage hint is the path constraint (must end in '.px'), but there is no mention of context or exclusions.

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: it specifies the scope (company-financial claims via SEC EDGAR + XBRL), lists the verdict types (confirmed, approximately_correct, refuted, inconclusive, unsupported), and describes the output structure (extracted form, actual value with citation, percent delta). This goes well beyond the annotations.

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

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

The description is concise, consisting of three sentences that are logically ordered: purpose, usage trigger with examples, and scope/output details. There is no wasted text, and 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?

Despite the lack of an output schema, the description explains the return values in sufficient detail (verdict, structured form, actual value with citation, percent delta). It also specifies the current scope (company financials) and limitations, making the tool's behavior clear 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?

The input schema already covers the single parameter 'claim' with a description. The description enriches it with concrete examples ('Apple's FY2024 revenue was $400 billion') and clarifies the nature of acceptable claims. Since schema coverage is 100%, the baseline is 3, and the description adds meaningful context, earning a 4.

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

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

The description clearly states the tool's purpose: 'Fact-check, verify, validate, or confirm/refute a natural-language factual claim or statement against authoritative sources.' It provides a specific verb and resource, and distinguishes itself from sibling tools like query_table or compare_entities by focusing on claim verification.

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

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

The description includes clear usage triggers: 'Use when an agent needs to check whether something a user said is true' and provides example phrasing. It also notes that the tool replaces 4-6 sequential calls, giving context on efficiency. However, it does not explicitly exclude alternative tools or state when not to use it, which prevents a perfect score.

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