Merriam Webster

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. The description adds valuable behavioral context: it defaults to a free model, requires BYO key for Anthropic, and returns per-model {score, confidence, signals, raw_response} plus combined view. No contradictions with annotations.

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

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

Two sentences, front-loaded with main action and output. Second sentence adds key usage detail (default model, API key). No fluff, every word earns its place.

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

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

For a tool with no output schema, the description adequately explains return format (per-model fields and combined view). Cover all parameters and usage scenarios (free vs paid). Sufficient for an agent to understand inputs and outputs.

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?

All 4 parameters have schema descriptions (100% coverage), and the description adds extra meaning: explains default model for 'models', clarifies _apiKey is only needed for Anthropic, gives examples for 'entity' and 'context'. 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 probes LLMs for knowledge about business/brand/product/topic and returns visibility scores. It specifies the verb 'probe', the resource (LLMs), and the output (score per model). Distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on multi-model visibility scoring.

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

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

Explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Describes default model and optional Anthropic probe with BYO key, giving clear context for when to use. Does not explicitly state when not to use or name alternatives among siblings, but the context is strong enough for an agent.

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

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

Annotations already provide readOnlyHint and idempotentHint. The description adds valuable context: it routes to 3,411 tools, fills arguments, and returns structured answers with stable citation URIs. No contradictions with annotations.

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

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

Well-structured: starts with priority statement, lists domains, explains mechanism, ends with examples. Every sentence adds value, though it is somewhat long. Could be slightly more 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 6 parameters (all aliases) and no output schema, the description adequately covers tool behavior, return format (citations), and use cases. Missing details on error handling or rate limits, but overall sufficient 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 coverage is 100% with descriptions for all aliases. The description adds examples and clarifies that the parameter is a natural language question. The baseline is 3, but the examples and usage guidance elevate it 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 routes factual questions to structured data sources, explicitly distinguishing it from web search and listing many domains (SEC filings, FDA data, etc.). The verb 'ask' and resource 'pipeworx' are clear, with examples like 'current US unemployment rate'.

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 'PREFER OVER WEB SEARCH' and provides extensive use cases with example queries. However, it does not compare against sibling tools like 'validate_claim' or 'bet_research', leaving some ambiguity on when to use this meta-tool vs more specific siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds significant behavioral context: resolution, classification, fan-out, response shapes, resolver contract, parent event extractor, news fields, safety for low-confidence matches, closed markets, and wide spreads. This goes beyond what annotations provide.

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

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

The description is lengthy but well-structured, front-loaded with core purpose and usage. It uses headings (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) to organize information. While dense, every sentence adds value; however, it could be more concise by trimming some examples 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 and lack of output schema, the description covers all necessary details: response shapes, resolver contract with confidence levels, parent event extraction, news fields with fallback info, safety mechanisms for low-confidence and closed markets, and wide-spread warnings. It is complete for an agent to use correctly.

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

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

Schema coverage is 100%; each parameter has a description. The description adds further meaning: explains market input formats (slug, URL, question), depth options (quick vs thorough), and include_raw trade-offs (summarized vs full payloads). This enriches the schema information.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It provides specific verb and resource, lists classifiers, fan-out examples, and distinguishes from sibling tools like polymarket_edges by focusing on single bet 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?

Explicit usage guidance is given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also advises inspecting market_match_confidence before trusting analysis. However, it does not explicitly state when not to use this tool or mention alternatives, though the sibling context implies alternatives exist.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds detailed behavioral traits: data sources (EDGAR/XBRL, FAERS), fiscal year handling, sorting by primary metric, and citation URIs. No contradictions.

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

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

The description is informative but somewhat verbose. However, it front-loads the purpose and usage, and every sentence adds value. Minor conciseness improvements possible.

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 (paired data + citation URIs). It covers all necessary details for correct invocation, including constraints and data sources.

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 described). The description adds significant meaning: explains data sources and metrics for each entity type, and clarifies that values are tickers/CIKs or drug names, going 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 uses specific verbs and resources (e.g., 'side-by-side comparison of 2–5 companies or drugs') and distinguishes from sequential single-pack lookups, making the tool's purpose highly 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 explicitly states to prefer this tool over sequential lookups when comparing entities, and provides example queries. It lacks explicit when-not-to-use scenarios but the 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. The description adds that the tool 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly'. This provides behavioral context beyond annotations.

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

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

The description is two sentences, front-loading the core purpose and usage guidance. Every sentence adds value: first defines what it does and lists domains, second explains the return format and when to call it. No unnecessary words.

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

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

Given the tool's simplicity (one core param, no output schema), the description is complete. It explains the purpose, input format, return value, and ideal usage scenario. No gaps remain for correct 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 coverage is 100%, so baseline is 3. The description adds value by providing example queries and clarifying that 'query' accepts natural language. It also notes aliases, though already in schema. This helps the agent understand 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 'Find tools by describing the data or task' and lists many example domains. This makes the tool's purpose specific and distinct from sibling tools, which are domain-specific tools themselves. The verb 'discover' and resource 'tools' are explicit.

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

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

The description advises 'Call this FIRST when you have many tools available and want to see the option set'. This provides clear context for when to use the tool. While it doesn't list alternatives or when-not-to-use, the strong recommendation to call it first implicitly guides the agent.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds substantial context: lists data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), return fields (cik, company_name, recent_filings with URIs, fundamentals, patents with sunset note, news, LEI), and explains the patents soft-fail. No contradiction.

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

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

Single dense paragraph with front-loaded examples. Contains all necessary information without fluff. Could be slightly more structured (e.g., bullet points for return fields) but remains 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 thoroughly explains the return structure: cik, company_name, recent_filings (with URIs and limit of 5), fundamentals (specific fields and sort order), patents (with sunset note), news (fallback chain), and LEI. This is complete for an agent to understand expected output.

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

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

Schema description coverage is 100% with clear descriptions for both parameters. The description adds value with concrete examples ('AAPL' or '0000320193'), clarifies that type is only 'company', and reiterates that names are not supported. This goes beyond the schema's basic enums and types.

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 explicitly states the tool provides a 'full cross-source profile of a US public company'. Examples like 'Tell me about X', 'research Acme', etc., clarify the trigger phrases. Distinguishes from siblings by preferring this over chaining single-pack lookups and mentioning resolve_entity for name resolution.

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 directs agents to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. Also states names are not supported and to use resolve_entity first if only a name is available. Includes details on patents soft-fail and fallback behavior.

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 destructiveHint and readOnlyHint, so description's 'Delete' adds no new behavioral traits. It adds usage context but not additional behavioral details like auth or rate limits.

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

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

Two sentences, front-loaded with action. Every sentence is necessary: action, usage guidance, related tools. 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 simple tool with one parameter, no output schema, and clear annotations, description covers purpose, usage, and related tools completely.

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

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

Schema coverage is 100% for the single parameter 'key' with a clear description. Description does not add extra meaning beyond what schema provides.

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

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

Description clearly states 'Delete a previously stored memory by key', specifying verb and resource. It distinguishes from siblings '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: 'stale context, task done, clear sensitive data'. Also mentions complementary tools 'remember' and 'recall', providing alternatives and 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 safe, read-only, idempotent behavior. Description adds context that tool fetches page and extracts specific elements, which is consistent and adds value beyond annotations.

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

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

Description is three concisely written sentences that front-load the main purpose. No unnecessary words or repetition.

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

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

For a simple tool with 2 parameters and no output schema, description covers purpose, usage, and output format. Could mention error handling or dynamic content, but it's sufficient.

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

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

Schema coverage is 100% with adequate descriptions for both parameters. Description does not add extra meaning or constraints beyond what schema provides, so baseline 3 is appropriate.

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

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

Description uses specific verb 'Generate' and resource 'llms.txt file', clearly states it fetches page, extracts title/description/key links, and outputs standard markdown. Distinguishes from sibling tools which are unrelated.

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

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

Description explicitly lists three use cases: client indexing, own project drafting, competitor auditing. Not when-not-to-use or alternatives, but use cases are clear and relevant.

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 include daily rate limit of 5 per identifier, free usage, and that feedback doesn't count against tool-call quota. Annotations are all false, so description carries the burden. 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?

Every sentence adds value, front-loaded with purpose and usage. Well-structured paragraphs with clear separation of instructions and constraints. No fluff.

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

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

Fully covers purpose, usage scenarios, key constraints (rate limit, quota), and team process. No output schema is needed for a feedback tool; description is 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% and the description adds nuance to the 'type' enum (e.g., 'data_gap' definition) and advises on message content. No parameter info missing, and description enriches 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 is for submitting feedback about bugs, missing features, or praise, distinguishing it from siblings like 'ask_pipeworx' or 'discover_tools' which serve different purposes.

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

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

Explicitly details when to use (bug, feature/data_gap, praise) and provides clear instructions (describe in terms of Pipeworx tools/packs, don't paste user prompt). Also mentions rate limits and quota exemption.

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 source (CF analytics-engine), privacy (no PII), and caching (5min-1h). 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 and well-structured, with the core purpose in the first sentence, followed by use cases and technical details. Every sentence adds value without fluff.

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

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

Given the simple input schema (1 optional param) and no output schema, the description sufficiently covers what the tool returns, how it works, and when to use it. 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?

Only one parameter with full schema coverage (enum, description). The description adds semantics by explaining how shorter vs longer windows affect results ('what's hot now' vs 'steady-state demand').

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

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

The description explicitly states the tool returns top tools, top packs, and total call volume over a recent window, with specific use cases. It clearly distinguishes from siblings by focusing on trending data rather than queries or entity profiles.

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

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

The description lists three concrete use cases (discovering hot data sources, confirming canonical choice, seeing alignment with trends) but does not explicitly state when not to use it or name alternative tools. However, the context is clear given the unique functionality.

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?

Discloses detailed algorithmic behavior beyond annotations: walks child markets, checks monotonicity, computes partition_check, semantic anchor (≥0.30 Jaccard similarity), partition filter (placeholder slugs). Annotations already indicate read-only, idempotent, open-world; description adds rich context about internal logic and edge cases.

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

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

Front-loaded with the requirement and modes, but description is long and somewhat dense. Some redundancy between main text and schema parameter descriptions. Still well-organized with clear sections and examples.

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

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

Given the tool's complexity (two modes, multiple checks), the description is thorough. Covers response format (opportunities[], partition_check), edge cases (placeholder slugs, Jaccard similarity), and limitations. No output schema, but description compensates by detailing return structure.

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

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

Schema description coverage is 100%, so baseline is 3. However, description adds significant value by explaining the difference between event and topic modes, providing examples, and describing behavioral implications (e.g., cross-event mode catches patterns single-event misses). Goes well beyond schema details.

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

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

Description clearly states 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks' with specific verb and resource. It distinguishes between two modes (event and topic) and implies differentiation from sibling tools like polymarket_edges and polymarket_kalshi_spread.

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 the mandatory requirement of providing one of 'event' or 'topic', and gives clear guidance on when to use each mode with examples (e.g., 'event (recommended for a specific market)', 'topic (for cross-event scanning)'). Also warns that calling with no args fails.

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 far beyond the annotations (readOnlyHint, idempotentHint, etc.) by detailing the three output segments, precise model families, edge calculation details (e.g., slippage, Kelly capping), diagnostics for empty segments, and caching behavior ('Cached 1h at the KV level keyed on all knobs'). This fully discloses the tool's behavior.

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

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

The description is long but well-structured with bold headings for segments and a clear separation of concepts. Every sentence adds value, though it could be slightly more concise without losing information. The front-loaded purpose sentence 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?

Despite no output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics) and the fields on each opportunity (edge_pp_net, kelly_fraction, etc.). For a complex tool with 9 parameters, this is complete enough for an agent to use correctly.

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

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

Schema coverage is 100%, but the description adds substantial meaning for parameters like min_kelly, min_partition_leg_kelly, and the tradeable-edge knobs (min_liquidity, max_spread_pp) by explaining their role in filtering and the edge calculation context. It also clarifies how min_partition_leg_kelly applies differently from min_kelly.

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 and returns opportunities where Pipeworx data disagrees with market price, with the specific purpose 'what should I bet on today'. It distinguishes from siblings like polymarket_arbitrage by focusing on model-driven edge rather than pure arbitrage.

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

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

The description explains the tool is built for agents to discover opportunities without paging hundreds of markets, and provides context on when to use it (discovering edges). However, it lacks explicit exclusion criteria or direct comparison to siblings like polymarket_arbitrage, though the usage context is clear enough for most agents.

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?

Provides extensive behavioral details beyond annotations, including compatibility_warning conditions, temporal alignment, skipped cross-type/subtype counters, and response structure. No contradiction with annotations.

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

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

Front-loaded with core purpose, then explains modes, response, and safety fields. Slightly long but justified by complexity; no waste.

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

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

Despite no output schema, description fully explains return values, safety warnings, temporal alignment, and edge cases. Very complete for a complex tool.

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

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

Adds meaning beyond schema by explaining topic shortcuts, override behavior, and examples. Schema coverage is 100%, but description still adds substantial 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?

First sentence clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. Distinguishes from siblings like polymarket_arbitrage by focusing on two venues.

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

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

Describes two modes (topic and explicit) and explains that most pre-mapped topics are not tradeable. However, lacks explicit comparison to sibling tools like polymarket_arbitrage for when not to use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds scope (scoped to identifier) and behavior (omit key to list all). 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?

Three sentences, front-loaded with core action. 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?

For a simple tool with one optional parameter, description covers purpose, usage, scope, and pairing. No output schema, but return value is implied. Could mention listing returns an array, but not critical.

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 that omitting the key lists all keys, which is not explicit in the schema description. Adds usage context.

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 verb ('retrieve' or 'list') and resource ('value saved via remember' or 'all saved keys'). It distinguishes from siblings by specifying 'remember' for saving and 'forget' for deleting.

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 to use for looking up stored context and mentions pairing with remember and forget. 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?

Discloses internal fan-out to multiple sources (SEC, GDELT/GNews, USPTO), fallback logic, and soft-fail for USPTO due to API sunset. Adds significant context beyond annotations which already indicate read-only, idempotent, non-destructive.

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 information-dense but well-structured, starting with purpose, then behavior, then parameters. Could be slightly tightened but 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 no output schema, description explains return format (grouped sources, total_changes, URIs) and contrasts with entity_profile. Covers all important aspects for correct use.

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

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

Schema has 100% coverage with descriptions; description adds relative shorthand examples, default suggestion ('30d'), and explanation of CIK format, which is helpful 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 it provides a change feed for a company over a time window, using phrases like 'What's new with X', and explicitly distinguishes from sibling tool entity_profile.

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

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

Explicitly says when to use this tool vs entity_profile, and describes fallback behavior between GDELT and GNews, providing clear guidance on behavior under rate limits or errors.

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 behavioral context beyond annotations: scope by identifier, persistent vs. 24-hour retention for anonymous, and pairing with recall/forget. Annotations already provide idempotentHint, readOnlyHint, destructiveHint; description complements well 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?

Four sentences, each providing essential information: purpose, usage trigger, storage details, and pairing. No fluff, efficient 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?

Complete for the complexity: two parameters, no output schema. Covers purpose, usage, persistence, and scope. 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%, so baseline 3. Description adds examples for key and value, but schema descriptions already cover their meaning. No additional semantic depth beyond 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 'Save data the agent will need to reuse later' with a specific verb (save) and resource (key-value memory across conversations/sessions). It distinguishes from sibling tools recall and forget.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward... so you don't have to look it up again.' Also pairs with recall and forget. No explicit when-not, 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 declare the tool as read-only, idempotent, and non-destructive. The description adds value by revealing internal behavior: cascading through multiple lookup endpoints, auto-disambiguation for companies, and returning citation URIs. This context helps agents understand the tool's composite nature and avoid redundant lookups.

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

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

The description is a single paragraph but is well-organized: starts with example queries, then purpose, then detailed type breakdown. Every sentence contributes value. Slightly verbose with upfront examples, but not wasteful; could be tighter with bullet points, but still effective.

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

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

Given no output schema, the description adequately explains return values for each type and the lookups involved. It covers input flexibility (ticker, CIK, name for company; brand or generic for drug). Error handling and rate limits are not mentioned, but for this simple two-parameter tool, it is sufficiently complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the return types for each 'type' value (ticker+CIK+company_name for company; RxCUI+ingredient+brand for drug) and providing examples for 'value' (AAPL, 0000320193, ozempic). This is helpful beyond the schema.

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

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

The description clearly states the tool's purpose: resolving a user-spoken name to a canonical/official identifier (ticker, CIK, RxCUI, etc.) for companies and drugs. It provides specific example queries and distinguishes itself from siblings by positioning it as the first step when an ID is needed, replacing 2-3 manual lookups.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' giving clear contextual guidance. It also details supported types and input formats. However, it does not explicitly state when not to use this tool or mention specific sibling alternatives for further steps.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) already declare safe, read-only behavior. The description adds valuable context: it probes each entity via ai_visibility_check, ranks by score, and returns a ranked list with 'score, confidence, signal density per entity.' It also notes that the first entity is treated as the subject. No contradiction with annotations.

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

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

Two sentences with zero waste. The first sentence states purpose and action; the second adds usage context and return details. Information is front-loaded and every sentence earns its place.

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

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

Given the 4 parameters (all described in schema), rich annotations, and no output schema, the description covers: what the tool does, how it works (probing, ranking), when to use (competitive audits), what it returns (score, confidence, signal density), and the treatment of the first entity. It is sufficiently complete for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds no new parameter-level information beyond what is already in the schema (e.g., first entity as subject is already documented). It repeats the schema's 'context' description without enhancing it.

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 ('compare,' 'probe,' 'rank,' 'surface') and clearly identifies the resource ('AI visibility across multiple entities side-by-side'). It distinguishes itself from sibling tools like 'ai_visibility_check' (single entity) and 'compare_entities' (generic 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?

Provides a concrete use case ('competitive AI-marketing audits') and an example question, giving clear context for when to use. It mentions the underlying sibling tool 'ai_visibility_check' but does not explicitly state when not to use it or specify alternatives for single-entity queries.

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

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

The description adds significant behavioral context beyond annotations: it fans out to external services, notes first measurement can take 5-30s, and explains partial failures degrade gracefully. Annotations already indicate read-only, idempotent, non-destructive behavior, and the description complements these 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 front-loaded with the core purpose and efficiently conveys complex behavior, return structure, and limitations in a few sentences. Every sentence adds value, with no redundancy or filler.

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

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

Given the tool's complexity and lack of output schema, the description comprehensively explains return fields, failure modes, and ecosystem scope. It fully equips an agent to understand what the tool does and what to expect.

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

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

Schema already covers both parameters with descriptions (100% coverage). The description restates version defaults and scoped package acceptance but does not add substantial new meaning. A score of 3 is appropriate as the schema carries the burden.

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

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

The description clearly states the tool performs a composite check for adding npm packages, combining data from deps.dev and bundlephobia. It uniquely distinguishes itself from siblings by its specific focus on npm package safety, size, and popularity, which is not covered by other 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 states when to use: 'is X safe / popular / small' or 'what does adding lodash cost me'. Also provides clear exclusions: 'NPM ecosystem only in v1' and directs users to deps.dev:version directly for other ecosystems. Mentions partial failure handling, providing complete usage guidance.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description adds behavioral traits: it returns specific verdict types, structured form, actual value with citation, and delta. It also discloses the data source (SEC EDGAR+XBRL) and efficiency gains, providing rich context for the agent.

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

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

The description is a single paragraph that effectively front-loads example phrases and includes key details (domain, verdict types, benefits). It is slightly verbose but each sentence adds value, achieving a good balance.

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 fully compensates by listing return types (verdict, extracted form, actual value, citation, delta). It covers purpose, usage, domain, data source, and efficiency, making the tool understandable without additional context.

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

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

With 100% schema coverage and a single parameter, the description adds value by providing extensive examples ('Apple's FY2024 revenue...') and explaining the domain scope, which enhances the schema's description without being redundant.

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

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

The description clearly states the tool performs 'natural-language claim verification against authoritative sources' and specifies the domain (company-financial claims for public US companies via SEC EDGAR+XBRL). It distinguishes itself from sibling tools by being the only claim verification tool, with a unique 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?

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and limits support to company-financial claims for public US companies. It implies when not to use but does not name specific alternative tools, leaving a slight gap.

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