Market Spread

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

Beyond annotations (readOnly, idempotent, etc.), the description discloses that Anthropic calls require a user-provided API key with direct billing, and specifies the return format (per-model {score, confidence, signals, raw_response} + combined view). No contradiction with annotations.

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

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

The description is concise (4 sentences), front-loaded with the core purpose, and structured logically: what it does, default behavior, optional extension, and output format. 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 no output schema, the description fully explains the return format and covers all necessary aspects: purpose, models, API key, disambiguation via context parameter. The tool's behavior is completely specified for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that `_apiKey` is passed straight through to api.anthropic.com, which clarifies its usage. This extra context justifies a 4.

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

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

The description clearly states the action ('Probe one or more LLMs for what they know') and the resource (business/brand/product/topic), with a specific scoring output (0-100). It distinguishes from siblings by focusing on LLM visibility probing, unlike e.g., 'scan_competitor_ai_presence' which likely does something different.

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 mentions use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the optional API key. However, it does not explicitly state when not to use this tool vs sibling tools, though context makes it clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds useful context about routing to 4,774 tools, returning structured answers with citation URIs, and performance tier.

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

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

Well-structured with prioritized information: preference, capabilities, usage guidance, examples, alternatives. Every sentence adds value with no wasted words.

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

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

Given no output schema, description explains return format (structured answer with citation URIs). Covers when to use, what it can answer, examples, and tier compatibility. Fully 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 covers 100% of parameters with descriptions. The description does not add new parameter semantics beyond what schema provides, meeting 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 answers factual questions using authoritative structured data, with specific examples and explicit distinction from siblings like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and details when to use alternatives (grounded for hallucination-resistant answers, deep_research for broad questions).

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, openWorldHint, idempotentHint, destructiveHint=false. Description adds fine-grained behavioral details: refusal reasons list, return structure {answer, evidence, confidence, source, fetched_at, refusal_reason}. 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 relatively long but well-organized with key purpose in first sentence, then details, usage guidance, and cost trade-off. Every sentence adds value; no redundant 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?

Complete for a tool without output schema: describes return structure on success and failure, lists all possible refusal reasons, explains the extra LLM call cost. Addresses typical agent concerns about reliability and when to 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 coverage is 100% with all 6 parameters aliased to 'question'. Description lists aliases but provides no additional semantic nuance beyond what the schema already conveys. Baseline 3 is appropriate given high schema coverage.

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

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

Description explicitly states verb 'answers' with a specific modality ('hallucination-resistant'), clearly distinguishes from sibling 'ask_pipeworx' for casual lookups. Mentions routing, extraction from tool results, and applicability to high-stakes reads.

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 specifies when to use ('high-stakes reads where answer will be quoted/cited/acted on') and when to prefer alternative ('prefer ask_pipeworx for casual lookups'). Also notes cost trade-off of one extra LLM call.

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 extensively details behavioral traits including resolution matching, fan-out logic, response structure, safety mechanisms (low-confidence short-circuit, closed market handling), wide-spread warnings, and resolution-rule risks. It adds substantial value beyond the annotations, which already indicate idempotent and read-only behavior. 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 long but well-structured with labeled sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.), making key information discoverable. It front-loads the main purpose and use. While it could be more concise, the depth is justified by the tool's complexity.

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

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

Despite the absence of an output schema, the description covers all critical aspects: input variations, resolution logic, fan-out behavior, response structure, error cases (low-confidence, closed markets, wide spreads), and resolution-rule risks. An agent has sufficient information 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?

All three parameters have schema descriptions (100% coverage). The description enriches them by explaining the 'market' parameter can be slug, URL, or question text; clarifying 'depth' as quick vs thorough with default; and detailing 'include_raw' with size implications. This additional context improves parameter understanding beyond the schema alone.

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

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

The description clearly states that the tool researches Polymarket bets by resolving markets, classifying bets, and fanning out to data packs. It provides specific input types and numerous examples, making its purpose unmistakable. While it doesn't explicitly differentiate from sibling tools, its breadth of functionality is so distinct that confusion is unlikely.

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 like 'should I bet on X' and 'what does the data say about Y', and provides guidance on interpreting results (e.g., checking resolver contract, resolution-rule risk). However, it does not mention when to avoid using this tool or suggest alternatives among siblings, which would improve the score.

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

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

Description details data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), specific metrics pulled, handling of off-calendar fiscal years, and sorting by primary metric. Annotations already indicate read-only/idempotent, and description adds significant behavioral context.

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

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

Description is efficiently structured with query examples at the start, followed by behavior, data sources, and return format. 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?

Given no output schema, the description covers return format (paired data + citation URIs), explains what it replaces (8-15 sequential lookups), and provides sufficient detail 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%, but description adds substantial meaning: explains what each type retrieves (e.g., LATEST 10-K data for companies, FAERS counts for drugs) and gives examples of values (tickers/CIKs for companies, drug names). This far exceeds 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?

Description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call, with specific examples of queries and types. It distinguishes itself from sequential lookups.

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

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

Explicitly advises ALWAYS PREFER this tool over sequential single-pack lookups when comparing entities. Provides context for when to use it and examples of query patterns.

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

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

The description adds significant behavioral context beyond the annotations (readOnlyHint, idempotentHint): parallel querying, error/reachability handling, divergence condition (Jaccard overlap), and honesty notes. 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 with clear sections (tool action, output, honesty note) but is slightly verbose. However, every sentence adds value—no wasted words. It earns a 4 rather than 5 due to minor redundancy (e.g., 'top matches' repeated).

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 return values (top matches, divergence summary), edge cases (venue timeouts, low token overlap), and interpretation guidance. It covers all necessary context for an agent to invoke correctly.

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

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

Schema coverage is 100% with decent descriptions for both parameters. The tool description adds value by clarifying default per_venue (3), max (5), and providing example topics. It could have detailed format requirements, but it already enhances 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's function: a cross-venue prediction-market landscape scanner for comparing pricing of a single topic across 5 named venues. It specifies the output (normalized matches and divergence summary) and distinguishes itself from siblings like 'polymarket_arbitrage' by noting it is not an executable arbitrage 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 guides when to use: for surface-level venue comparison and spotting divergence. It provides a clear 'when not to use' by stating it is not for executable arbitrage and directs to the 'polymarket_arbitrage' pack for that purpose. It also warns about interpretation of divergence.

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 account requirements, paid tier for 'thorough' depth, expected response time (15-60s), parallel decomposition behavior, return format (findings with citations and gaps), and limitation for current-news topics (empty gaps). Adds value beyond readOnlyHint and idempotentHint annotations.

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

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

Information-dense and front-loaded with critical account info, but somewhat verbose with specific numbers (1242, 4774) that could be omitted. Still well-structured per sentence earning 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?

Fully describes purpose, parameters, return format, limitations, and expected use cases despite lack of output schema. No gaps for a complex parallel research 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%, baseline 3. Description adds concrete meaning: 'quick=3, standard=5, thorough=8' for depth, and clarifies question should be natural language and multi-part. Slightly exceeds 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?

Description specifies exact function: decomposed multi-source research across 1242 structured data sources using parallel tool routing. Clearly distinguishes from sibling tools like ask_pipeworx by contrasting scope ('broad/multi-part' vs 'single lookup').

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: when to use (broad/multi-part structured questions), when not (current news, single lookups), and alternatives (ask_pipeworx for single lookups / news). Also notes account requirements and tier limitations.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' 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 somewhat lengthy but well-structured: purpose first, then usage, then output details. Every sentence adds value, though could be slightly tighter.

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 6 params and no output schema, the description adequately explains what returns (tools with schemas). Missing explicit mention of default limit (but schema has it). Overall complete.

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

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

Schema coverage is 100% with descriptions for all 6 params. Description adds value by listing aliases for query (task, q, description, search) and providing examples. Goes slightly beyond 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?

Clearly states it finds tools by describing data/task and lists many domains. It distinguishes from sibling tools like deep_research or search_within by specifying it's about discovering tools themselves.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear context for when to use.

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

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

Annotations already declare the tool as read-only, idempotent, open-world, and non-destructive. The description adds further behavioral details: it fans out across multiple sources, mentions the USPTO API sunset with soft-fail behavior, describes the GDELT→GNews fallback for news, and lists returned fields. No contradiction with annotations.

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

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

The description is fairly long but well-structured with example queries first, followed by details. Every sentence adds value, though it could be slightly more concise. It is front-loaded with the most important information.

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

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

Given the tool's complexity (multiple data sources, fallback behaviors, input constraints), the description covers all aspects: what it returns (cik, filings, fundamentals, patents, news, LEI), edge cases (patents soft-fail), and input requirements. No output schema exists, but the description compensates by listing return fields comprehensively.

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

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

Input schema covers both parameters with descriptions, so schema coverage is 100%. The description adds context by clarifying that type is currently limited to 'company' and that value must be a ticker or CIK, not a name. It also instructs to use resolve_entity for names. This adds useful usage nuance 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 provides a full cross-source profile of US public companies in one parallel call. It uses specific verbs like 'profile' and lists example queries, distinguishing it from sibling tools such as compare_entities or deep_research.

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

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

Explicitly states to prefer this over chaining single-pack lookups for holistic views. Provides clear usage instructions: support for ticker or CIK, and instructs to use resolve_entity first if only a name is available. No ambiguity in when to use.

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

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

The description aligns with annotations (destructiveHint: true) but does not add behavioral details beyond stating deletion. Annotations already convey the destructive nature, so the description adds minimal extra transparency.

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

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

The description is two sentences long, front-loading the action and then providing usage context. Every sentence is informative without waste.

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

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

For a simple tool with one parameter and clear annotations, the description fully covers the necessary context. No output schema is needed given the simplicity.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete'. The description does not add any additional meaning or formatting guidance beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the action (delete) and resource (memory by key), and distinguishes itself from sibling tools like 'remember' and 'recall' by specifying the use case of deletion.

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 scenarios for when to use (stale context, task done, clear sensitive data) and mentions pairing with related tools, though it lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: fetches the page, extracts title/description/key links, and emits standard markdown. It also notes the output is a single text blob ready for deployment, which 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 well-structured: first sentence states the main purpose and output, followed by the extraction process, then use cases. It is front-loaded and avoids redundancy, though the use cases list could be slightly trimmed.

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

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

Given no output schema, the description explains the output format (standard llms.txt markdown) and usage (drop at site-root/llms.txt). It covers the process and key aspects, but could mention error handling for invalid URLs or edge cases. Overall, it is complete for a simple tool with two parameters.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add significant parameter-level detail beyond the schema, but it does reinforce the purpose of the url parameter (fetching the page) and max_links (number of link entries). The use cases in the description help agents choose appropriate parameter values.

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

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

The description clearly states the verb 'Generate', the resource 'llms.txt file', and the purpose 'so AI crawlers can index the site cleanly'. It distinguishes from sibling tools by focusing specifically on llms.txt generation, not generic AI visibility.

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: getting a client's site indexed, drafting for own project, or auditing a competitor. It provides clear context for when to use the tool, though it does not explicitly state when not to use it or name alternative tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, openWorldHint. Description adds return fields and usage purpose, complementing annotations without contradiction.

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

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

Two concise sentences, front-loaded with purpose and return fields, zero waste. Efficient and clear.

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 simplicity (no output schema, 1 optional param), the description fully covers what the tool does, returns, and when to use. Complete and 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 description for the single optional parameter. No additional parameter info in tool description, but baseline 3 is appropriate as schema suffices.

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 'List the caller's active subscriptions' with specific return fields. Verb 'list' and resource 'subscriptions' are unambiguous, distinguishing from siblings like subscribe/unsubscribe.

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

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

Explicitly states when to use: 'review what you're monitoring before adding more or to find an id to cancel'. Provides clear context but lacks explicit when-not-to-use or 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?

Disclosures rate limit (5 per identifier per day), that it's free and doesn't count against tool-call quota. Annotations don't contradict; description adds useful behavioral context beyond annotations.

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

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

Description is concise (3 sentences) but packed with essential information. Front-loaded with purpose, followed by usage guidelines and behavioral notes. 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?

Covers all necessary aspects: purpose, when to use, how to write feedback, rate limits, and cost. No output schema needed for this tool; description is self-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?

Despite 100% schema coverage, description adds significant value by explaining each enum value in detail, specifying message length limits, and clarifying context usage. Goes well 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 the tool's purpose: sending feedback to Pipeworx team about bugs, features, or praise. It explicitly lists feedback categories (bug, feature/data_gap, praise) and distinguishes itself from sibling tools by being the dedicated feedback channel.

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 each feedback type: bug for wrong/stale data, feature/data_gap for missing tools, praise for positive experiences. Also gives best practices like describing in terms of tools/packs and avoiding end-user prompts.

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

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

Annotations already declare readOnly, idempotent, not destructive. Description adds self-aggregating, no PII, caching behavior (5min-1h), which is useful 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-loaded with key outcome, no fluff. Each sentence adds value.

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

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

No output schema, but description mentions 'top tools, top packs, total call volume'. Could benefit from specifying output format or pagination, but sufficient for a simple trending tool.

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

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

Schema covers 100% (single parameter with enum and description). Description adds context on window semantics (short=hot, long=steady-state).

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

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

Clearly states it returns top tools, packs, and call volume. Specific verb 'returns' and distinct resource (trending data). Differentiates from siblings like 'discover_tools' by focusing on trending metrics.

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

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

Lists three specific use cases and explains window choice (hot vs steady-state). No 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 indicate read-only, idempotent, non-destructive. Description adds rich behavioral details: scanning top ~200 markets, walking child markets, monotonicity checks, partition sums, Jaccard similarity filter, placeholder filter, fill check against CLOB depth. 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?

Well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. However, it is quite dense with technical details (e.g., Jaccard threshold, placeholder percentage) that may overwhelm, 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?

Despite no output schema, description fully explains response structure (opportunities[] with fields, partition_check object) and fill check behavior. Covers all modes and edge cases, references sibling tool for custom sizing, making it complete for an agent to invoke correctly.

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

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

Input schema has 100% coverage with detailed descriptions for both parameters (event, topic). Description adds further context with concrete examples (e.g., 'fed-decision-may-2026') and behavioral details per mode, significantly exceeding 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?

Description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, and distinguishes three modes (no-args, event, topic). It uses specific verbs and resources, differentiating from siblings like 'polymarket_edges' or 'polymarket_fill_risk'.

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

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

Explicitly tells when to use each mode: no args for trending scan, event for specific market, topic for cross-event. Also provides when-not-to-trade guidance (fill check realizable_edge_pp ≤ 0) and directs to polymarket_fill_risk for custom sizing.

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

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

Annotations declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: caching behavior ('Cached 1h at the KV level keyed on all knobs'), detailed response structure (by_segment, diagnostics), and constraints like Fed bets excluded from ranking. 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 excessively verbose, spanning multiple paragraphs with detailed technical explanations of each model family and mathematical formulas. While informative, it is not concise; the key purpose and usage could be stated in 2-3 sentences. The structure front-loads the purpose but is cluttered with implementation details.

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

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

Given the complexity of 9 parameters and a rich response structure (by_segment with three segments, diagnostics, Fed exclusion), the description is remarkably complete. It explains the three model families, each with specific formulas, the tradeable-edge knobs, caching, and how to interpret empty segments via _diagnostics. No output schema exists, so the detailed response description compensates fully.

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

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

Schema coverage is 100% with detailed descriptions for all 9 parameters. The description adds context on how parameters like min_partition_leg_kelly relate to the model families, but it does not significantly supplement the schema beyond providing overarching context. Baseline 3 is justified, and the extra context merits 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 scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on model-driven edge scanning and from polymarket_edge_tracker by being a discovery tool. The purpose is specific and actionable.

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 it is built for agents to discover opportunities without paging hundreds of markets, and it provides tradeable-edge knobs like min_liquidity and max_spread_pp to filter opportunities. However, it does not explicitly mention when not to use this tool versus alternatives like polymarket_arbitrage, leaving some ambiguity. The guidance is strong but not exhaustive.

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: details on returned tracked/expired/snapshot_dates, trend computation, boundary conditions (TTL, gaps), and data derivation. No contradiction with annotations.

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

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

The description is thorough but somewhat lengthy. It is front-loaded with purpose and structured by response fields. Every sentence adds information, though slight trimming could improve conciseness without losing detail.

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, the description fully explains return structures and limitations (TTL, gap handling). It provides enough context for an AI agent to understand what the tool returns and its constraints.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining defaults (days=14, window='1wk'), clamping range (max 30), and window family interpretation, enhancing the schema's definition.

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

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

The description states a specific verb-resource pair ('edge persistence and decay telemetry') and answers a concrete question. It clearly distinguishes from sibling polymarket_edges by focusing on historical tracking.

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

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

The description explains when to use the tool: to distinguish between fresh and old edges. It implicitly contrasts with polymarket_edges but does not explicitly list alternatives or when not to use beyond the stated use case.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context by detailing what the tool returns (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict) and warns about partial fills and forced directional risk. This goes well beyond the annotations, providing the agent with critical safety and outcome information.

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

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

The description is well-structured with capitalized section headers (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) that make it easy to scan. Every sentence adds necessary detail without redundancy. Despite length, it is efficiently organized for an AI agent to parse.

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?

With no output schema, the description bears full responsibility for explaining return values, which it does comprehensively for both modes. It covers all key outputs (verdict, slippage, fill details, profit, thin legs, max clean notional, forced directional risk) and ties them to the tool's purpose of assessing capturability and risk. The description is complete for the tool's complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra value by explaining how size_usd is interpreted differently in single-market vs basket modes, and how the side parameter defaults to auto in basket mode based on partition sum. This additional context improves parameter understanding beyond what the schema provides.

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

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

The description clearly states it checks 'realizable-vs-theoretical edge against live CLOB order-book depth' with two explicit modes (single-market and basket). It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use this tool before acting on those signals, making the purpose unambiguous.

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

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

The description explicitly says to use this before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500. It provides clear context about when to use (before large trades or arbitrage signals) and warns about the risk of partial fills converting to directional positions, effectively guiding agent 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 indicate read-only, idempotent, open-world. Description adds significant context: compatibility warnings, temporal alignment checks, skipped comparison counters. No contradictions. Thoroughly discloses behavior beyond annotations.

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

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

Description is long but well-structured: purpose, modes, response fields, safety fields. Front-loaded with main idea. Every sentence adds value, though 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?

No output schema exists, so description carries full burden. It explains response fields (leg prices, top spreads, compatibility warnings, temporal alignment, skip counters). Covers edge cases and limitations comprehensively.

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 100%, so baseline is 3. The description adds meaning by explaining the two modes, listing topic options, and describing how explicit parameters override topic. Provides context not in 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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts vs explicit tickers) and explains the meaning of the spread. Differentiated from sibling tools like polymarket_arbitrage.

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

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

Provides explicit guidance on when to use each mode: topic for pre-mapped macros, explicit for custom pairings. Also warns about compatibility and temporal misalignment conditions that make spreads meaningless. Lacks explicit 'do not use' scenarios but covers proper usage well.

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, non-destructive. Description adds context: omitting key lists all keys, scoped to identifier. 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?

Efficient, front-loaded sentences. No wasted words. All information is relevant and well-structured.

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

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

Sufficient for a simple read-only tool with one optional parameter. Covers retrieval, listing, scoping, and tool relationships despite no output schema.

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

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

Schema has 100% coverage. Description adds value by explaining the omit-to-list behavior and pairing with remember/forget, beyond schema's brief description.

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

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

Clearly states the tool retrieves a saved value or lists all keys, explicitly distinguishes from siblings '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?

Describes when to use: to look up previously stored context without re-deriving. Provides examples (ticker, address, notes). Mentions scoping but lacks explicit exclusion cases.

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

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

The description states that setting mark_read:true flags returned events as read, which is a state mutation. However, annotations declare readOnlyHint=true, indicating the tool is read-only. This is a direct contradiction, reducing transparency.

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

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

The description is four sentences, front-loaded with the main purpose, and provides essential details without redundancy. 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?

With 5 parameters, no output schema, the description covers key return fields and parameters. It mentions the HTTP alternative. It could be slightly more complete by mentioning the default limit and 'unread_only' behavior, but overall sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic value for 'type' (with example 'sec_8k'), 'since' (ISO timestamp), and 'mark_read' (explains the side effect). It does not detail 'limit' or 'unread_only' explicitly, but the schema covers them.

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 fired events from the subscription feed, specifying it returns recent alerts with source, citation_uri, and raw payload. This distinguishes it from sibling tools like list_subscriptions or subscribe.

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

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

The description mentions that polling works fine and provides an alternative HTTP endpoint, but does not explicitly compare to other tools or state when not to use this tool. It gives contextual 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?

The description discloses multiple behavioral traits beyond the annotations: it fans out to SEC EDGAR, GDELT→GNews fallback, and USPTO, explains the fallback logic ('GDELT preferred, GNews when rate-limited or 5xx'), notes a soft-fail for USPTO (PatentsView API sunset May 2025), and describes the return structure (changes[] grouped by source, total_changes, pipeworx:// citation URIs). Annotations already declare readOnly, openWorld, idempotent, non-destructive, and the description complements these with specific source behaviors.

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 concise, front-loading example queries and then explaining functionality in a single paragraph. Every sentence adds information without redundancy. Slightly more structured formatting could improve readability, but it is efficient.

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

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

Given the tool's complexity (multiple data sources, fallback logic, date parsing) and the absence of an output schema, the description is remarkably complete. It covers the return structure, source behavior, failure modes, and when to use an alternative. An agent would have sufficient information to invoke this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing concrete examples for 'since' ('2026-04-01' or '7d', '30d', '3m', '1y') and clarifies that 'value' accepts ticker or zero-padded CIK, and 'type' is only 'company'. This enriches the parameter 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 begins with concrete example queries ('What's new with X', 'latest on Y') and explicitly states it is a 'change feed for a company in the last N days/weeks/months in ONE parallel call'. It distinguishes itself from the sibling tool 'entity_profile' by noting when to use that instead. This makes the tool's specific verb and resource very clear.

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

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

The description provides explicit usage context with example inputs (ticker, CIK, date formats) and tells the agent when NOT to use this tool: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' This is excellent guidance.

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

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

Annotations already indicate idempotentHint=true, destructiveHint=false, readOnlyHint=false. The description adds context: storage is key-value scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours. This goes beyond annotations but could mention idempotency explicitly.

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 eight sentences, all valuable, front-loaded with purpose, then usage, then details. 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?

The tool is simple (2 string params, no output schema, no enums, no nested objects). The description covers scope, persistence, and pairing with siblings, making it fully adequate for a memory store tool with rich annotations.

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

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

Schema description coverage is 100% with each parameter described. The description adds that memory is 'key-value scoped by your identifier', providing context beyond the schema. Baseline is 3, and the additional scoping info merits 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 'Save data the agent will need to reuse later', specifying the verb (save) and resource (data for later reuse). It distinguishes from sibling tools like recall and forget, which are mentioned as partners.

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

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

The description explicitly states when to use: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also mentions alternatives: 'Pair with recall to retrieve later, forget to delete.'

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds that the tool calls multiple internal endpoints and provides return value details (ticker, CIK, citation URI). No contradiction.

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

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

The description is concise but could benefit from more structure (e.g., bullet points for supported types). It is front-loaded with user-facing examples, making it effective. No unnecessary sentences.

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

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

Given the tool's simplicity (2 params, no output schema), the description fully explains the return values and internal cascading. It covers all necessary context for an agent to use the tool correctly.

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

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

Schema coverage is 100%. The description enriches parameters by providing concrete input examples (e.g., 'AAPL' for company, 'ozempic' for drug) and clarifying accepted formats. This adds value beyond the schema.

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

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

The description starts with clear examples like 'What's the ticker for…' and identifies the core purpose: mapping user-spoken names to canonical IDs. It also distinguishes from siblings by stating 'Use FIRST whenever you have a name but need an ID.'

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

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

The description explicitly states when to use ('when you have a name but need an ID') and supports two entity types. It also notes that each call cascades internally, replacing multiple manual lookups. No explicit alternatives are given, but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds meaningful behavior: it is a composite tool that calls ai_visibility_check multiple times, aggregates, and returns a ranked list with specific fields. No contradictions found.

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

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

The description is extremely concise—two sentences plus a relevant quote. Every sentence serves a purpose, and the most important action (compare AI visibility) is front-loaded.

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

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

Despite lacking an output schema, the description explicitly states what is returned (ranked list with score, confidence, signal density per entity). This is sufficient given the tool's moderate complexity and rich annotations.

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

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

Schema coverage is 100%, so baseline is 3. The description does not elaborate on parameters beyond the schema; it mentions entities but the schema already describes them. No extra semantic value added for models, _apiKey, or 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?

The description clearly states the tool compares AI visibility across multiple entities side-by-side, with specific outputs like ranking by score and surfacing most/least recognized. It uses strong verbs and resource identification, and the detail (score, confidence, signal density) distinguishes it from vague alternatives.

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 ('competitive AI-marketing audits') and a concrete example question, suggesting when to use. It implicitly contrasts with ai_visibility_check by noting it probes each entity with that tool, but lacks explicit exclusions or comparison to siblings like compare_entities.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds critical behavioral details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed list included. 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?

Well-structured: purpose first, then usage, then caveats. Somewhat verbose but every sentence adds value. Could be slightly more concise, but 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 complexity (two APIs, partial failures) and no output schema, description covers return fields, behavior, limitations, and alternatives. Complete for effective tool selection and 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 coverage is 100% with clear descriptions for both parameters. Description adds minor value: scoped packages accepted, version defaults to latest. Baseline 3 is appropriate, but extra context raises 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?

Description clearly states the tool's purpose: a composite check for npm packages using deps.dev and bundlephobia. It specifies the verb 'check', resource 'npm package', and distinguishes from any sibling by its multi-source aggregate nature.

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: 'Use whenever an agent asks 'is X safe / popular / small''. Also mentions NPM ecosystem only and points to alternative for other ecosystems (deps.dev:version directly). This helps agent decide when to use this vs other 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?

Beyond annotations (readOnlyHint, etc.), the description discloses the embedding model (BGE-base-en), windowing (500-char overlapping windows), character cap (200K with truncation and flagging), and return format (offsets, scores). 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 concise (5-6 sentences) and front-loaded: first sentence gives core function, then usage context, then technical details. Every sentence adds value without redundancy.

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

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

Given no output schema, the description adequately explains return values (passages, offsets, scores). It also covers technical constraints (model, window size, char limit) and suggests a sibling tool workflow. For a retrieval tool, it is complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the purpose of each parameter in context (e.g., 'Pass the text you already pulled', 'natural-language query') and provides query examples. This goes beyond the schema descriptions.

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

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

The description clearly states the tool performs semantic search inside a fetched record, specifying inputs (text + query) and outputs (top-N passages with offsets and scores). It distinguishes itself from siblings by mentioning pairing with ask_pipeworx_grounded and being for oversized records.

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

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

The description explicitly says when to use: 'Use when the record is too big to cram into the prompt' and suggests an alternative workflow (fetch with gateway, ground over passages). It does not explicitly state when not to use, but the context is clear.

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

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

Description discloses important behavioral traits: requires OAuth, returns subscription id, delivery channels with specific constraints (SMS 10/day, webhook HMAC signing, auto-disable after 10 failures). The secret is returned once. All annotations are consistent (readOnlyHint false, etc.) and description adds value beyond them.

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

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

Description is lengthy but well-structured with clear sections for supported types and delivery channels. Every sentence adds value. Could be slightly more concise, 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 subscription creation tool with 3 parameters and no output schema, the description covers all parameter semantics, behavioral constraints, prerequisites, and return value. It is complete given the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds extra meaning: explains item codes with examples (e.g., '5.02' = officer change), topic examples, delivery details like phone verification requirement and webhook signing. This enriches the schema.

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

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

Description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It identifies the action (create), resource (subscription), and distinguishes from siblings like unsubscribe and list_subscriptions.

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

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

Description provides context: requires Pipeworx OAuth account, anonymous/BYO cannot persist. It details delivery channels and constraints (SMS cap, webhook verification). It does not explicitly state when not to use or mention alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. Description adds valuable context about being an onboarding tool that returns example questions, without contradicting 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 detailed but includes some redundancy (listing categories and then mentioning catalog). However, it is well-structured with front-loaded trigger phrases and focused on adding value.

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

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

For a simple tool with one optional parameter and no output schema, the description fully explains return value (category-bucketed examples with tool shapes) and usage context. 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% for the single optional param 'topic', with description of allowed values. Description adds meaning by explaining how omitting gives full spread while passing a topic focuses results.

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

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

Description clearly states the tool returns category-bucketed example questions with tool+argument shapes, serving as the onboarding entry point. It distinguishes from siblings by being the first tool to use when unfamiliar with Pipeworx capabilities.

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 this tool first when agent does not know what Pipeworx can do, and provides guidance on calling with no arguments for full spread or with topic for focus. Also mentions alternative meta-tools like ask_pipeworx.

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 key behaviors beyond annotations: ownership enforcement (only cancel own subscriptions) and soft-delete (row deactivated, not deleted, preserving history). Annotations already cover idempotency and non-destructiveness.

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

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

Two concise sentences that are front-loaded with the action. Every sentence provides useful information without redundancy.

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

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

For a simple mutation with one parameter, full schema coverage, and annotations, the description is complete. No output schema is needed.

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

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

Schema has 100% coverage with a description for 'id'. The tool description adds no further parameter details beyond stating it's canceled by id, which is already clear from 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 states 'Cancel a subscription by id,' clearly specifying the action and resource. It distinguishes from sibling tools like 'subscribe' (creates) and 'list_subscriptions' (lists).

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

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

The description implies usage context and mentions ownership enforcement, but does not explicitly state when not to use or compare with alternatives. The purpose is clear enough for selection.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral details: it uses SEC EDGAR + XBRL, returns a verdict with specific categories and a structured form with a citation, and describes the delta. This goes beyond annotations without contradicting them.

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

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

The description is fairly long but well-organized, starting with example intents and then defining the tool's role. Each sentence adds value, though some redundancy exists (e.g., listing verdict types both in description and implied by schema). It could be slightly more concise but remains clear.

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 a single parameter and no output schema, the description covers what the tool returns (verdict, structured form, citation, delta) adequately. However, it does not explain the 'pipeworx://' citation format or mention any pagination or error handling. For its scope, it is reasonably complete.

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

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

Schema coverage is 100% with a clear description for the only parameter 'claim'. The description provides examples of natural-language claim formats, but the schema already sufficiently describes the parameter. The additional examples are helpful but not essential 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: verifying natural-language claims against authoritative sources, with specific examples and domain (company-financial claims). It includes common user intents and positions itself as replacing multiple sequential calls, distinguishing it from siblings.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and limits the scope to company-financial claims. It does not explicitly state when not to use, but the domain restriction is clear. The reference to replacing 4-6 sequential calls provides additional context.

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

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

Annotations already declare readOnlyHint, openWorldHint, destructiveHint. Description adds value by clarifying 'Keyless' (no auth needed) and explaining implied_probability behavior for multi-outcome markets, which is 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, each with clear purpose: core function, usage context, and output detail. No fluff, front-loaded with action verb.

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 specifies return format. Annotations cover safety. Low complexity tool with 2 params, no enums. Sufficient for informed selection.

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

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

With 100% schema coverage, description adds context that query is a 'Question / topic text' and venue is a single value from a list, plus the output structure (top 5 matches) which relates to parameter use. This adds value over schema alone.

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

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

Description clearly states 'fetch one venue's current top 5 matches for a query' with specific verb and resource, and distinguishes from sibling compare_topic by saying 'useful after compare_topic to look closer at one venue'.

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 (after compare_topic) and implies single-venue scope. Lacks explicit when-not-to-use, but context is clear enough.

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