Crypto Feeds

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 valuable context: default model is free, Anthropic requires BYO key and charges, and the returned data structure (score, confidence, signals, raw_response). 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?

Three informative sentences, front-loaded with the core action. No redundancy; each sentence adds essential detail. Structure is clear and 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 4 parameters and no output schema, the description covers the main functionality, return structure, and use cases. It could mention rate limits or that it's a read operation, but annotations handle safety. Overall adequate for agent 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 every parameter is documented. The description adds practical context beyond schema: default model selection, that _apiKey is passed straight through, and the disambiguation purpose of context. This meaningfully 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 verb 'probe' and 'score', the resource 'LLMs for visibility', and the scope 'per model' with a combined view. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on arbitrary entities and multi-LLM probing.

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 use cases are provided: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains when to use _apiKey for Anthropic. However, it does not explicitly contrast with sibling tools like 'scan_competitor_ai_presence'.

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

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

Description adds that it routes to 4,482 tools across 1,129 sources, returns structured answers with stable citation URIs, and works on every tier. Annotations already indicate read-only and idempotent, so 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 lengthy but well-structured, front-loading purpose and examples, with each sentence contributing distinct information. Slightly verbose 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 100% parameter coverage, no output schema, and the tool's complexity, the description is comprehensive: purpose, usage, alternatives, and examples are fully covered.

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 aliases for the single question parameter. Description reinforces natural language usage and provides examples, adding value beyond the schema.

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

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

The description clearly states the tool answers factual questions about structured data with citations, listing many domains. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly advises to prefer over web search, provides when-to-use and step-up alternatives with specific conditions and examples.

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

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

Annotations already declare readOnly, idempotent, open world, and not destructive. The description adds detailed behavioral information: return JSON structure (answer, evidence, confidence, source, etc.) and explicit refusal cases with reasons. It also notes the extra LLM call cost. This goes beyond annotations, but could mention more about openWorldHint implications.

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 front-loaded with the key purpose. While somewhat verbose, every sentence adds necessary detail (comparison to sibling, return format, use cases). Could be slightly tighter but still effectively 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?

Given the tool's complexity (6 parameter aliases, no output schema), the description compensates by detailing the return JSON and refusal reasons. It also contrasts with sibling tools. The output schema is not provided, but the description's explanation is sufficient for an agent to understand the response.

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

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

Input schema has 100% description coverage, with each parameter described as an alias for 'question.' The description adds only 'Your question in natural language' which is already implied. No additional semantic value beyond schema.

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

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

The description starts with a clear, specific statement: 'Hallucination-resistant answer mode for high-stakes reads.' It explains exactly what the tool does (extracts answer only from tool result) and distinguishes it from its sibling 'ask_pipeworx' which lacks this grounded extraction.

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: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and provides examples (financial verdicts, legal claims, etc.). Also clearly advises when not to use: 'prefer ask_pipeworx for casual lookups' due to extra cost.

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 behavior beyond annotations: fan-out patterns, response shapes, resolver contract, parent_event extraction, news fallback mechanisms, safety short-circuits, closed market handling, wide-spread market notes, and cancellation rule parsing. 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?

While front-loaded with the main purpose, the description is very long and includes many detailed edge cases and examples. It could be more concise without losing essential information, but the structure is logical.

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

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

Given the tool's complexity (no output schema, many fan-out categories, safety mechanisms), the description is remarkably complete. It covers market matching, parent events, news fallback, resolution rules, and response shapes, leaving no significant gaps.

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

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

Schema coverage is 100% and the description adds value: explains 'market' accepts slug, URL, or question text; describes 'depth' via examples; details 'include_raw' with its effect on response size. This adds meaning beyond the schema definitions.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data. It uses specific verbs ('resolves', 'classifies', 'fans out') and distinguishes from siblings like polymarket_edges and polymarket_arbitrage by focusing on a single bet research with comprehensive data.

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

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

Explicit use cases are provided ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). It explains when the tool short-circuits (low confidence, closed markets) but does not explicitly state when not to use it or suggest alternatives, though the sibling tools list implies other options.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, sorting by primary metric, and returns citation URIs. No contradictions with annotations.

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

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

The description is slightly verbose but efficiently front-loaded with examples and key instructions. Each sentence adds value, though it could be tightened 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 (two entity types, multiple metrics, sorting, citations) and lack of output schema, the description thoroughly explains inputs, data sources, behavior, and output format. It is fully complete for the 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 meaning beyond the schema by explaining what each entity type retrieves (financial metrics for companies, adverse-event counts for drugs) and what value formats are expected (tickers/CIKs, drug names). This 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 tool's purpose: side-by-side comparison of 2-5 companies or drugs. It provides explicit use cases ('X vs Y', 'rank these companies') and distinguishes from sibling tools like entity_profile which are single-entity 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 instructs to prefer this tool over sequential single-pack lookups, and provides examples of when to use it ('which is bigger', 'rank these companies'). This clear guidance helps the agent choose the right tool.

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

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

Annotations set readOnlyHint, openWorldHint, idempotentHint, destructiveHint to false. Description adds: requires sign-in, depth pricing, decomposition and parallel routing, output format (findings with evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[]), latency (15-60s), and that it does not invent. 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 somewhat long but well-structured with critical info first (account required, alternative). Every sentence adds value. Acceptable for 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?

For a tool with no output schema, the description fully characterizes the return format (findings packet with verbatim evidence, confidence, source, fetched_at, citation, gaps) and behavior. Covers prerequisites, limitations, and expected latency. 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 has 100% coverage with descriptions. Description adds value by explaining the depth enum values: 'quick=3, standard=5 (default), thorough=8 (paid plans)' and that question can be broad/multi-part. This goes beyond the schema's simple description.

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

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

The description clearly states it performs grounded multi-source research over structured data, decomposes questions into facets, and distinguishes itself from siblings like ask_pipeworx and ask_pipeworx. Specific verbs like 'decomposes', 'routes', 'returns' make the action concrete.

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 (broad/multi-part structured data questions) and when not (breaking news, colloquial current-news). Provides fallback tool alternatives (ask_pipeworx) and explains prerequisites (account, paid plan for 'thorough' depth). No ambiguity.

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

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

Discloses key behaviors beyond annotations: returns top-N tools with full schemas, ready to call directly without second lookup. Annotations already indicate read-only/idempotent, 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?

Front-loaded with purpose and usage; each sentence adds information. Slightly long but all content earns its place. Could be tightened slightly but not padded.

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?

Describes return value (tools with schemas, ready to call) and context for use. No output schema, so no return format details needed. Covers all necessary aspects for a discovery tool.

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

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

Schema coverage is 100%, baseline 3. Description adds value by listing aliases, giving examples, and explaining the query parameter accepts natural language, exceeding schema detail.

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?

Explicitly states 'find tools' with specific verbs (browse, search, look up, discover) and lists many domains. Unambiguously distinguishes from sibling tools as a discovery gateway.

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

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

Provides clear when-to-use advice ('Call this FIRST' when many tools available) and implies alternatives by stating 'not just one answer'. Lacks explicit when-not-to-use or named alternatives but still strong guidance.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavior details: it fans out across multiple sources in one parallel call, soft-fails on USPTO, and returns specific fields. This complements the annotations 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?

The description is a single cohesive paragraph that front-loads example queries and states the core purpose immediately. While it is lengthy, all sentences add value by detailing sources, returns, and limitations. It could be slightly more concise, but the structure is logical and 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 thoroughly explains what the tool returns (cik, recent_filings with URIs, fundamentals, patents, news, LEI) and notes the USPTO soft-fail. It also clarifies constraints (ticker/CIK only) and the parallel call nature. This is comprehensive for a 2-parameter tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description reinforces the schema by explaining that 'type' is limited to 'company' and 'value' accepts ticker or CIK. It adds important context that names are not supported, which goes beyond the schema's description. This extra guidance merits a score above 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 returns a full cross-source profile of US public companies. It provides multiple example queries and lists the data sources (SEC, XBRL, USPTO, news, GLEIF), making the purpose unmistakable. It also distinguishes from sibling tools like compare_entities and resolve_entity.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also specifies when not to use: 'Names not supported — use resolve_entity first if you only have a name.' This provides clear guidance and points to an alternative tool.

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

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

Annotations (readOnlyHint, idempotentHint) already indicate safe behavior; description adds CF-robustness with fallback proxy behavior and normalization, going beyond annotations.

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

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

Two sentences: first covers purpose and behavior, second gives usage guidance. Front-loaded, no redundant information.

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

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

Good given no output schema: covers purpose, behavior, usage. Missing description of return format (normalized items) which would be helpful.

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 does not add new meaning beyond schema; mentions normalization but not specific syntax or format 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?

The description clearly states the tool fetches and normalizes any RSS/Atom/RDF feed by URL. It distinguishes from siblings like list_feeds (curated sources) and read_feed (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?

Explicitly recommends using list_feeds first for curated sources, providing context for when to choose an alternative. Lacks explicit when-not-to-use but is clear enough.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description only restates 'Delete', adding no additional behavioral context beyond annotations.

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

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

Two sentences, front-loaded with action, zero extra words. Efficient and to the point.

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 delete tool with one parameter and no output schema, the description covers all essential information, especially given 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 has 100% coverage with description 'Memory key to delete'. Description does not add further meaning beyond schema.

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

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

Clearly states 'Delete a previously stored memory by key' with specific verb and resource. Distinguishes from siblings 'remember' and 'recall'.

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 when to use: stale context, task done, clear sensitive data. Mentions pairing with related tools, providing clear 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?

The description adds value beyond annotations by detailing the process (fetching page, extracting title/description/links) and output format (single text blob). 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 and front-loaded with the main action and output. 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?

Given the tool's simplicity (2 params, no output schema, read-only/idempotent annotations), the description sufficiently covers purpose, usage, and output. Lacks error handling details but is adequate.

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

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

Schema coverage is 100%, but the description adds context: default for max_links is 25, max 50. This goes beyond the schema descriptions, which only state the field names 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?

The description clearly states it generates a production-ready llms.txt file, specifies the actions (fetches, extracts, emits), and gives concrete use cases. It distinguishes itself from sibling tools by focusing on llms.txt generation.

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 specific use cases (client site indexing, drafting for own project, auditing competitor) but does not explicitly state when not to use it or how it compares to siblings like scan_competitor_ai_presence.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, providing a clear safety profile. The description adds that feeds are 'curated crypto' and lists return fields, enriching the context 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?

Two sentences with no wasted words. First sentence states purpose and output fields, second sentence adds filter options and sibling reference. Perfectly 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?

For a simple list tool with full parameter documentation and rich annotations, the description covers purpose, filters, and sibling linkage. It doesn't mention pagination or ordering, but the open-world hint suggests variability, and the lack of output schema is compensated by listing return fields.

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 parameter descriptions. The description paraphrases the schema ('optionally filter by category or keyword') without adding new meaning, so the 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 it lists curated crypto feeds and shows which fields are returned. It distinguishes itself from the sibling tool `read_feed` by prompting to pass an id to that tool, but doesn't explicitly contrast with other list-like siblings like `discover_tools`.

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

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

The description specifies when to use this tool: to list feeds with optional filters. It provides explicit guidance on using `read_feed` for detailed feed lookups by id, but doesn't address other potential 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?

Description adds context beyond annotations by specifying return fields and default behavior (active only), though annotations already cover read-only, idempotent, and non-destructive nature.

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

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

Two sentences with no redundancy: first defines function, second provides usage guidance. Perfectly front-loaded.

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

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

Given simple tool with one optional parameter, no output schema, and robust annotations, description is complete: covers purpose, usage, return fields, and default behavior.

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

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

Schema describes parameter fully, and description adds meaning by clarifying default behavior (active only) and practical use case, though it does not repeat 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 'List the caller's active subscriptions' with specific verb and resource, and distinguishes from siblings subscribe and unsubscribe by focusing on listing.

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 using the tool to review subscriptions before adding more or to find an id to cancel, providing clear when-to-use and implied 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?

Discloses rate limiting ('5 per identifier per day') and that it's free without counting against tool-call quota. Annotations provide no safety hints, so this context is crucial. 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?

Six sentences, front-loaded with purpose, then use cases, then constraints. No unnecessary words. Every sentence adds value.

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

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

For a simple feedback tool with 3 params (2 required), the description covers purpose, usage, limitations, and does not need output schema. Complete and 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% already, so baseline is 3. The description adds value by explaining how to use the 'type' enum categories and advising to be specific in 'message'. Also clarifies that 'context' is optional but helpful. This raises it above 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 states the tool's purpose clearly: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies categories (bug, feature, data_gap, praise) and distinguishes from sibling tools which are research/analysis focused.

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

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

Provides explicit when to use: 'when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... when something worked surprisingly well.' Also instructs to 'describe the issue in terms of Pipeworx tools/packs' and not paste 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 and idempotent. Description adds data source origin (CF analytics-engine), no PII, and caching behavior (5min-1h), providing useful operational 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 about 100 words, front-loaded with core purpose, well-structured with bullet points. 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 the tool's simplicity, good annotations, and full schema, the description is complete. It tells what returns, how it works, and provides use cases. No missing info.

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 description. The tool description does not add new parameter information beyond what is already in the schema, so it meets the baseline.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a window. It distinguishes from siblings by specifying it shows what other AI agents are calling, not just general tool discovery.

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

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

Lists three specific use cases in bullet points, providing clear guidance on when to use. Does not explicitly mention when not to use, but context makes it clear.

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

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

Annotations indicate read-only, open-world, idempotent. The description adds significant behavioral details: required parameters, check types (monotonicity, partition), semantic anchor (Jaccard similarity), partition filter, fill check against live CLOB depth, and actions like 'do not trade it'. 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 detailed and well-structured, with key requirements front-loaded. Every sentence adds value, but it is somewhat lengthy. A minor reduction in wordiness could improve conciseness without losing clarity.

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

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

Despite no output schema, the description comprehensively explains what the tool returns (opportunities array, partition_check, fill_check), including details like 'gap_pp', 'suggested_trade', 'reasoning', and 'thin_legs'. It also references a related tool for custom sizing, making it self-contained.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds substantial context beyond schema: examples of slugs and seed questions, explanation of behavior per mode, and the Jaccard similarity filter. This elevates the parameter semantics well above 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 that the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between event mode (single-event) and topic mode (cross-event), providing a specific verb ('find arbitrage opportunities') and resource ('Polymarket'). This differentiates it from siblings like polymarket_edges.

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

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

The description explicitly says when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. It warns that 'call with no args fails'. It mentions polymarket_fill_risk for custom sizing, providing an alternative. However, it does not directly compare to sibling tools like polymarket_edges, which is a minor gap.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: caching is 1h at the KV level, it explains the response structure (by_segment, fed_candidates, diagnostics), and details how filters work. 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 very long (several paragraphs) and delves into deep technical details about model families and internal mechanics. While it is front-loaded with the purpose, the verbosity may hinder quick parsing by an AI agent. It could be more concise by summarizing the model families and focusing on key behavioral points.

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

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

Despite the lack of an output schema, the description thoroughly explains the response structure: by_segment with three segments, fed_candidates, and _diagnostics. It also covers edge cases like 'why a segment is empty' and '24h-move warning'. Given the tool's complexity (9 parameters, no output schema), this description is exceptionally 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 all parameters described. The description adds value beyond the schema by explaining default values, rationale (e.g., slippage_pp mentions Polymarket fees), and operational details (e.g., min_partition_leg_kelly explains why partition arbs have kelly_fraction_half=0 at parent level). This enhances 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?

Description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It uses the specific phrase 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price', which is a specific verb+resource. This distinguishes it from sibling tools like polymarket_arbitrage, polymarket_edge_tracker, etc., which have different scopes.

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 frames the tool for 'what should I bet on today' and explains that it discovers opportunities without paging hundreds of markets. It also details tradeable-edge knobs and category filters. However, it does not explicitly state when to avoid using this tool or compare directly with sibling 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=true, etc. The description adds significant behavioral context: history depth bounded by 60-day TTL, snapshots written on cache-miss causing gaps, and details on decay calculation (daily closes, not intraday). 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 lengthy but every sentence adds value: core purpose, response structure, and limitations. It is front-loaded with the key question it answers. Minor reduction possible but fully justified.

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

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

No output schema, so the description must explain return values. It thoroughly details tracked[], expired[], and snapshot_dates[] fields, including meanings of trend, decay_pp_per_day, lifespan_days, etc. Complete for a time-series analytics tool.

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

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

Schema coverage is 100% with both parameters described. The description adds default values, range for 'days' (clamp 2-30), and explains the 'window' parameter options. This adds meaningful interpretation beyond the schema.

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

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

The description clearly states it provides edge persistence and decay telemetry from daily polymarket_edges snapshots. It answers a specific question about edge age and trend, and distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis instead of raw snapshots.

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

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

The description implies usage for understanding edge age and decay, and contrasts with raw edge data ('a fresh wide edge and a 3-week-old wide edge are different trades'). However, it does not explicitly state when not to use or provide alternatives, though the context is clear given sibling 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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), explains size_usd interpretation for buys vs sells and basket vs single-market, and warns about thin books and partial fills. No contradiction with annotations.

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

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

The description is lengthy but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). It front-loads the core purpose and requirements. However, some details like the full list of return fields could be more concisely presented, especially given the absence of an output schema. A slightly tighter structure would earn a 5.

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, 4 parameters, no output schema), the description is remarkably complete: it covers both modes, all parameters and their defaults/interactions, return fields, behavioral warnings, and usage context. An agent has sufficient information to select and 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%, and the description adds crucial meaning beyond the schema: clarifies that market and event are mutually exclusive, explains side defaults for each mode, defines size_usd differently for single-market (spend/target) vs basket (settlement notional), and notes the clamp range. This fully compensates for any schema ambiguity.

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 performs a realizable-vs-theoretical edge check against live order-book depth, with two distinct modes (single-market and basket). It lists specific return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly specifies required parameters ('REQUIRES one of market or event'), when to use it ('before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'), and warns against risks like partial basket fills converting an arb into unhedged directional position.

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 the readOnlyHint and idempotent annotations, the description extensively details compatibility conditions, temporal alignment, and skipped leg comparisons, providing deep behavioral insight.

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 (TWO MODES, RESPONSE, SAFETY FIELDS) and every sentence adds value, though it is somewhat lengthy.

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 sufficiently explains response structure and safety fields, but could still benefit from specifying exact JSON keys.

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

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

Although schema descriptions are complete, the description adds context on how the two modes interact and the semantics of the pre-mapped shortcuts, enhancing 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 computes cross-venue spread between Kalshi and Polymarket, which is distinct from intra-venue siblings like polymarket_arbitrage. It specifies two modes and provides exact 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 explains four usage modes (topic vs explicit) and warns that pre-mapped topics often yield compatibility warnings, guiding the agent when to expect meaningful results. However, it does not directly compare to alternative tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds that it returns normalized items with specific fields and supports optional filtering. The additional context is useful but not extensive beyond the annotations.

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

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

Two sentences, front-loaded with purpose and output, then optional filter. No wasted words. 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?

For a read-only tool with strong annotations, the description adequately covers the purpose, input, output format, and optional filtering. It does not address pagination or error cases, but that is acceptable given the complexity. Differentiation from sibling tools could improve completeness.

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

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

Schema coverage is 100% and schema descriptions already specify the feed id source and the query filter. The description restates that the filter is optional and over title/summary, providing no new semantic value beyond the schema.

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

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

The description clearly states it reads a curated crypto feed by id and returns normalized items. It references list_feeds as the source for the id, which adds context. However, it does not explicitly differentiate from the sibling tool 'fetch_feed', which may have similar functionality.

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

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

The description implies the tool should be used after list_feeds to get an id, and mentions optional keyword filtering. It does not explicitly state when to use this tool versus alternatives like fetch_feed, nor when not to use it.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds useful behavioral context beyond annotations: scoping to identifier (anonymous IP, BYO key hash, account ID) and concrete examples of stored values, enhancing understanding 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?

Four sentences, each purposeful: first defines action, second gives use case, third explains scope, fourth pairs with siblings. No redundancy, front-loaded with key verb, 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?

For a simple read tool with one optional parameter, the description is complete. It explains functionality, usage scenarios, scoping, and relationships with siblings. No output schema is needed for such a straightforward tool.

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

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

Schema coverage is 100% for the single 'key' parameter, so baseline is 3. The description adds meaning with practical examples (ticker, address, notes) and clarifies behavior when omitted (list all keys), providing value beyond the schema.

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

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

The description clearly states the tool retrieves values saved via remember or lists all keys, with specific verb 'Retrieve' and resource 'value previously saved via remember'. It distinguishes from sibling tools like remember and forget by naming them.

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

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

The description provides clear usage context: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It names sibling tools (remember, forget) but does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds behavioral details: mark_read:true flags events read so next call shows newer ones, and mentions the same feed is available via HTTP for scripts/dashboards. Exceeds annotation-only info.

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, no fluff, front-loads purpose and return fields. Could be slightly shorter but effectively communicates key points.

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

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

No output schema, but description explains return fields (source, citation_uri, raw payload). Covers key behaviors: mark_read, unread_only, polling. Lacks mention of pagination beyond limit, but adequate for a read-only tool with good 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 has 100% coverage with descriptions. Description adds value beyond schema by giving concrete example for type ('sec_8k'), clarifying mark_read effect, and emphasizing ISO timestamp for since. Baseline 3, extra semantic context earns a 4.

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

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

Description clearly states it pulls fired events from the subscription feed, specifies return fields (source, citation_uri, raw payload), and distinguishes from sibling tools like fetch_feed and read_feed by focusing on alerts with mark_read and filtering options.

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

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

Provides clear usage context: filter by type and since, mark_read behavior, and mentions polling works and alternative HTTP access. Does not explicitly exclude cases but implicit 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?

Beyond annotations (readOnly, idempotent, etc.), description details fallback logic, API sunset warning for USPTO, and return structure (changes[], total_changes, citation URIs).

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 packed with information but remains coherent. It starts with example queries, then explains behavior. Slightly long but 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?

Despite no output schema, description sufficiently explains return format. Covers complex behavior (multi-source, fallback, soft-fail) and provides alternative tool reference.

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

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

Schema coverage is 100%. Description adds examples for `since` (ISO dates, relative shorthand), clarifies `type` only supports 'company', and recommends '30d' for monitoring.

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 provides a change feed for a company with sources like SEC EDGAR, GDELT/GNews, and USPTO, and distinguishes it 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?

Provides clear example queries, parameter usage tips (e.g., '30d' for monitoring), fallback behavior, and explicit when-not-to-use guidance (use entity_profile for static profiles).

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 behavior beyond annotations: key-value pair scoped by identifier, persistence for authenticated vs anonymous sessions. Consistent with annotations.

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

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

Three sentences, front-loaded with purpose, no redundancy, 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?

Covers purpose, usage, behavioral transparency, and sibling pairing. Lacks error handling or overwrite behavior, but sufficient for a simple key-value store.

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

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

Schema has 100% coverage with clear descriptions. Description adds usage examples but no new syntactic details. Baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for reuse, provides examples, and distinguishes from siblings '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 says when to use (discover something worth carrying forward), provides examples, and mentions pairing with recall/forget. Lacks explicit when-not instructions.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and nondestructive. The description adds value by explaining that each call cascades through several lookup endpoints internally and replaces multiple manual lookups, which provides useful behavioral context beyond annotations.

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

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

The description is well-structured and front-loaded with example queries. Every sentence adds value, and there is no unnecessary information.

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

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

Although no output schema is provided, the description explains what each entity type returns (e.g., ticker + CIK + company name for companies, RxCUI + ingredient + brand for drugs) and includes citation URIs. This completes the context for a resolution 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%, so baseline is 3. The description adds examples for the 'value' parameter and mentions auto-disambiguation for company type, which provides additional meaning beyond the schema.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers. It provides specific examples like tickers, CIKs, and RxCUI, and differentiates from sibling tools like compare_entities and entity_profile.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID.' It also lists supported entity types with examples, providing clear context. However, it does not explicitly state when not to use the tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by detailing the internal process (probing with ai_visibility_check, ranking, surfacing most/least recognized) and specifying returned fields (score, confidence, signal density). 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 two sentences, front-loaded with the core action, and includes purpose, method, use case, and output. Every word contributes 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 describes the return format (ranked list with per-entity score, confidence, signal density). It also references the sibling tool it uses internally ('ai_visibility_check'), providing full context for how the tool works. All parameters are covered in the schema.

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

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

Schema coverage is 100% with all parameters described. The description adds meaning by revealing that the first entity in the 'entities' array is treated as the 'subject' for narrative, which goes beyond the schema. It also provides context for how parameters like 'models' and 'context' are used in the probing process.

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', 'Probes', 'ranks', 'surfaces') and clearly states it compares multiple entities side-by-side, distinguishing it from the sibling tool 'ai_visibility_check' which probes a single entity. The resource is well-defined: AI visibility across 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?

The description explicitly frames the tool for competitive AI-marketing audits and gives a concrete example question. It clearly implies usage for multi-entity comparison against 'ai_visibility_check' for single entities, but does not explicitly state when not to use or list exclusions.

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

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

Annotations already provide readOnly, openWorld, idempotent, non-destructive hints. Description adds value by disclosing the fan-out across services, latency (5-30s for first bundlephobia measurement), graceful degradation with sources_failed field, and that the rest still returns on timeout. 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 moderately long but every sentence carries unique information. Front-loaded with the core composite check, then branches into usage guidance, ecosystem scope, and behavioral notes. Could be slightly tighter but still 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 no output schema, the description adequately explains return values (summary block fields, per-advisory detail, links, alternative versions). Covers edge cases (partial failures, latency, NPM-only) and provides a complete picture for an agent to understand tool behavior.

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

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

Schema coverage is 100% with both parameters described. Description adds context: accepts scoped packages (e.g., @types/node), version defaults to latest if omitted. While not extensive, it provides useful usage details beyond the schema.

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

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

The description clearly states it's a composite 'should I add this npm package' check combining multiple services (deps.dev, bundlephobia). It distinguishes from siblings by being specific to npm package analysis, while siblings like 'scan_competitor_ai_presence' cover different domains.

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 agent asks about safety, popularity, size, or cost of adding a package. Notes NPM-only limitation and suggests alternatives for other ecosystems (deps.dev:version directly). Also mentions partial failures and graceful degradation.

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, idempotentHint, etc. The description adds valuable behavioral details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged)', which goes beyond annotations.

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

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

Description is concise (~100 words), front-loaded with purpose, then usage, then technical details. Every sentence is informative with no redundancy.

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

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

No output schema, but description explains returns: 'top-N passages with character offsets and similarity scores'. Covers input constraints, behavior, and usage context adequately 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 coverage is 100%, baseline 3. The description adds context for 'text' ('Pass the text you already pulled') and explains 'query' with examples. For 'limit', it mentions default and range. 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 clearly states the tool performs semantic search inside a fetched record, with specific examples like SEC 10-K and articles. It distinguishes itself from siblings by mentioning pairing with 'ask_pipeworx_grounded'.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt' and 'Pairs with ask_pipeworx_grounded', providing clear context and alternative.

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

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

Adds significant behavioral context beyond annotations: requires OAuth account, delivery channel specifics (SMS cap, webhook signing and auto-disable), and returns subscription ID. 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 core purpose upfront, then details on types and delivery. Slightly verbose but every sentence adds value. Could be tighter, 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?

Comprehensive for a complex tool: covers prerequisites, return value, supported types, delivery options with constraints, and retry behavior. No output schema needed given the detail.

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 value with detailed examples for each type and param, and explains delivery constraints, making it more actionable.

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' with specific verb and resource. It distinguishes itself from siblings like list_subscriptions and unsubscribe by focusing on creation.

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

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

Provides clear context on when to use (create a subscription) and prerequisites (Pipeworx OAuth account). Does not explicitly state when not to use, but siblings handle other operations. Good guidance overall.

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, so the description adds limited behavioral context. It mentions returning categories and tool shapes, but doesn't detail pagination or response structure. 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 somewhat long but front-loaded with the key purpose and usage context. 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?

Despite no output schema, the description clearly states what is returned: 'category-bucketed example questions' with 'exact tool + argument shape'. This is sufficient for an onboarding tool, making it complete for its purpose.

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

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

The one parameter (topic) is fully described in the schema (100% coverage). The description adds value by listing valid topic values and explaining 'Omit for a cross-category spread', which is not in the schema.

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

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

The description clearly states the tool's purpose: it returns category-bucketed example questions with exact tool and argument shapes. It distinguishes itself as the onboarding entry point for new users, contrasting with siblings like ask_pipeworx or discover_tools.

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

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

Explicitly advises use 'FIRST when you do not yet know what Pipeworx can do' or to learn meta-tools. It does not explicitly state when not to use it, but the context is clear. Sibling tools are mentioned as meta-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 indicate idempotent and non-destructive nature. The description adds valuable context: ownership enforcement and soft-deactivation rather than deletion. 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?

Two sentences, front-loaded with action and key constraint. Every sentence adds value with no redundancy. 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?

For a simple tool with one parameter and no output schema, the description provides sufficient behavioral context (ownership, deactivation) and references siblings indirectly. It is complete enough 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 covers 100% of the single parameter with description. The description adds minimal extra meaning by referencing that the id comes from 'subscribe', which is helpful but not essential. Baseline 3 is appropriate.

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

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

The description clearly states it cancels a subscription by id, using a specific verb and resource. It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by describing the cancellation action and ownership enforcement.

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

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

The description implies when to use (to cancel one's own subscription) and includes constraints (ownership enforcement). It also explains that historical events remain, guiding agent behavior. However, it does not explicitly list 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context beyond these by detailing the data sources (SEC EDGAR + XBRL), the return format (verdict, actual value, citation, percent delta), and the version limitation ('v1 supports company-financial claims'). 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 detailed but efficient, starting with example queries, then stating purpose, scope, and return type. It is front-loaded with key information, though it could be slightly more concise by removing the initial list of example synonyms in quotes.

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

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

Given the tool has one parameter and no output schema, the description thoroughly explains the return values (verdict types, actual value, citation, delta) and the domain scope. It also notes version limitations. The information is sufficient for an agent to understand and 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?

The single parameter 'claim' has 100% schema description coverage. The tool description supplements this with concrete examples (e.g., 'Apple's FY2024 revenue was $400 billion'), adding meaningful usage context beyond the generic schema description.

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

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

The description clearly states the tool verifies natural-language claims against authoritative sources, specifically company-financial claims via SEC EDGAR and XBRL. It lists example queries and distinguishes itself by mentioning it replaces multiple sequential calls, though it does not explicitly name a sibling tool. The verb 'validate' and resource 'claim' are specific, and the domain is well-defined.

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

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

The description says 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the current domain of company-financial claims. However, it does not explicitly state when not to use it or suggest alternative tools for non-financial claims, which would improve guidance.

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