Security Feeds

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable context: free default model, BYO key for Anthropic, return structure per-model. No contradiction.

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

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

Three sentences, no wasted words. Front-loaded with purpose, then details. 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 4 params, no output schema, description explains return format (per-model fields + combined view). Covers optional usage and edge case (API key requirement). Complete for this complexity.

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

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

Schema coverage is 100%, baseline is 3. Description adds meaning: 'default model is Workers AI Llama-3.3-70b (free)' and explains _apiKey purpose and context parameter's role in disambiguation.

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

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

Description uses specific verb 'probe' and resources 'LLMs' with clear output 'score visibility (0-100) per model'. It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on multi-model scoring.

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

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

States use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Explains default model and when to provide _apiKey. Lacks explicit when-not-to-use but provides sufficient context.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds context: 'one fast call', 'works on every tier', 'returns the structured answer with stable pipeworx:// citation URIs'. No contradictions. Adds value beyond annotations by explaining routing and citation format.

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

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

Description is fairly long but well-structured: bold recommendation, functionality, guidance, examples. Front-loaded with key point. Each sentence earns its place, 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?

Given the tool's broad scope, the description covers purpose, usage, behavioral traits, and return format (structured answers with citations). No output schema needed; description explains. Complete for an agent to decide when to use.

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

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

Schema coverage is 100% with all 6 parameters (aliases for question) well-described. Description provides rich examples and clarifies the parameter is natural language, adding value beyond schema. Baseline 3, increased to 4 due to examples.

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

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

The description clearly states it is for asking questions about current/historical data from authoritative sources, routing to the appropriate tool. It distinguishes from siblings like ask_pipeworx_grounded, deep_research, and web search, with specific examples.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and provides guidance on when to use alternatives: 'Step up only when needed: for a hallucination-resistant single answer with verbatim evidence + confidence use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.' Also gives query 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which align with the description. The description adds critical behavioral details: it routes to the right tool, uses only tool result, returns refusal reasons, and costs an extra LLM call. 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 front-loaded with purpose and structured with examples of refusal reasons. It is somewhat lengthy but every sentence adds value; 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?

Despite missing output schema, the description thoroughly explains the return format (answer, evidence, confidence, etc.) and refusal scenarios. Given the tool's complexity and importance, the description is fully informative.

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

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

Schema description coverage is 100%, so baseline is 3. The description lists aliases for 'question' but does not add meaning beyond what the schema already provides. Adequate but not exceptional.

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

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

The description clearly defines the tool as a hallucination-resistant answer mode for high-stakes reads, specifying it extracts answers only from tool results. It distinguishes itself from the sibling 'ask_pipeworx' by focusing on grounded responses with evidence.

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 answers will be quoted, cited, or acted on, and where invention is unacceptable (e.g., financial verdicts, legal claims). Also advises preferring 'ask_pipeworx' for casual lookups, providing clear alternatives.

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

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

Annotations already indicate read-only, idempotent, open-world. Description adds extensive behavioral details: fan-out process, resolver contract, parent event extraction, news fallbacks, safety checks, wide-spread handling, cancellation rule parsing. Goes well beyond annotations.

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

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

Long but well-structured with sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.). Every sentence is informative given the tool's complexity. Not overly concise but justified.

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

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

Despite no output schema, the description covers response shapes, edge cases, safety mechanisms, and resolution details comprehensively. 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 coverage is 100%, all parameters described. Description adds examples, explains depth options, size implications of include_raw. Adds value beyond schema.

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

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

Clearly states it researches a Polymarket bet by pulling Pipeworx data. Specifies input formats (slug, URL, question text). Distinguishes from siblings like ask_pipeworx which are more general.

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

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

Explicitly says use for 'should I bet on X', 'what does the data say about Y', etc. While it doesn't list when not to use, the context of numerous sibling tools implies alternatives. Clear usage scenarios provided.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds detailed data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/clinical trials for drugs), handles edge cases (off-calendar fiscal years), and specifies sorting and return format with citation URIs. No contradiction with annotations.

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

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

Well-structured with user-friendly examples upfront, but slightly verbose with redundant emphasis on efficiency. Still earns its length.

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

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

Fully covers input, behavior, and output expectations. No output schema exists, but the description compensates by mentioning paired data and citation URIs. Adequate for a straightforward comparison 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 coverage is 100% but description enriches both parameters: 'type' with entity-specific data sources, 'values' with detailed format (tickers/CIKs vs drug names) and examples. This substantially aids correct parameter use.

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 opens with example queries that directly match user intent, clearly states it performs side-by-side comparison of 2–5 companies or drugs, and distinguishes from sibling tools like entity_profile which handles 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?

Explicitly prefers this tool over sequential lookups for comparisons. While it doesn't list excluded scenarios, the context is sufficiently clear for an agent to decide when to use.

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

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

Annotations already mark readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds rich behavioral context: account requirement, parallel execution, return format (findings packet with gaps), expected latency (15-60s), and limitations (empty gaps for out-of-catalog topics). 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 relatively long but well-structured and front-loaded with critical information (account requirement, fallback tool). Every sentence serves a purpose; the length is justified by the tool's complexity. Could be slightly trimmed but remains efficient.

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

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

Despite no output schema, the description fully explains what the tool returns (findings packet with evidence, citations, gaps) and its behavior (parallel decomposition, never invents). It covers prerequisites, error scenarios (empty gaps), and performance expectations. Complete for a complex tool.

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

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

Schema coverage is 100% with detailed descriptions for both parameters (including enum values and numeric equivalents for depth). The description does not add parameter-level semantics beyond what the schema provides, so 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 uses a specific verb ('decomposes', 'routes') and resource ('1127 STRUCTURED data sources', '4,476 tools') to clearly state what the tool does. It also distinguishes from siblings by noting when to use 'ask_pipeworx' instead, so purpose is unambiguous.

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

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

Explicitly provides when-to-use and when-not-to-use with clear alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and even addresses the sign-in requirement and fallback. This is exemplary.

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, destructiveHint) already indicate safe read operation. The description adds transparency about the response: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas — each result is ready to call directly.' This explains output format 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 a single paragraph that front-loads the purpose. It could be slightly more concise, but every sentence adds value (purpose, usage, return format). Structurally sound.

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 discovery tool with 6 parameters (1 required) and no output schema, the description covers return format, parameter intent, and usage context. It doesn't mention pagination or error handling, but for a discovery tool it is fairly complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description contextualizes the query parameter as 'natural language description of what you want to do' but adds minimal extra meaning beyond the schema's parameter descriptions.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides specific examples of domains (SEC filings, financials, etc.) and distinguishes itself from sibling tools by being the discovery entry point.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' It implies when not to use (if already know tool) but doesn't list alternatives explicitly.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint. The description adds significant behavioral context: lists all data sources fanned out (SEC, XBRL, USPTO, news, GLEIF), describes output fields, and discloses the USPTO PatentsView API sunset limitation. No contradictions.

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

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

The description is relatively long but front-loaded with examples and key guidance. Every sentence adds value, but minor redundancy (e.g., repeating 'names not supported' from schema). Still well-structured and functional.

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

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

No output schema exists, so the description must document return structure. It does so by listing all returned fields with details (e.g., URI format, sorted fundamentals). It covers the patents limitation and input constraints. Missing some edge cases (e.g., partial failures), but adequate for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by including practical examples ('AAPL', '0000320193') and explicitly stating that names are not supported, redirecting to resolve_entity. Adds a small but useful increment.

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 creates a full cross-source profile of a US public company. It provides example queries and explicitly contrasts with chaining single-source lookups, distinguishing it from siblings like deep_research and other research tools.

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

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

Explicitly states when to use ('ALWAYS PREFER over chaining... when user asks for a holistic view') and when not to use (names not supported), directing to resolve_entity as an alternative. Provides clear input guidance for ticker or CIK.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, so safety traits are well-covered. The description adds valuable context: 'CF-robust: fetches directly and falls back to a proxy if the source blocks the gateway', which is a key behavioral trait not in annotations. No contradictions.

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

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

Three sentences, each earning its place: purpose, robustness, and usage hint. Front-loaded with the core verb+resource. Zero waste or redundancy.

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

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

No output schema exists, and the description does not explain return values (e.g., normalized feed structure). While annotations and schema are rich, for a fetch tool the output format is important. Could specify normalization details or item fields. Partial 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%, so baseline is 3. The description adds minimal new meaning: it provides an example URL ('https://news.ycombinator.com/rss') and restates the limit and query descriptions already present in the schema. No additional constraints or semantics 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 'Fetch and normalize any RSS / Atom / RDF feed by URL' with a specific verb and resource. It distinguishes from the sibling 'list_feeds' by advising to use 'list_feeds first for curated sources', and from 'read_feed' by being the primary fetching tool.

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

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

Provides explicit guidance: 'Use list_feeds first for curated sources', indicating when to use an alternative. Also notes the CF-robust behavior (direct fetch with proxy fallback), which helps the agent decide when this tool is appropriate. Lacks explicit mention of when not to use compared to other siblings like 'read_feed'.

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

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

Annotations already provide 'destructiveHint: true' and 'idempotentHint: true'. The description adds context about when deletion is appropriate (stale context, sensitive data), which supplements the 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: first states action and resource, second gives usage guidance and pairing suggestion. No wasted words, front-loaded with key information.

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

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

For a simple delete tool with one parameter and annotations present, the description covers purpose, usage, and relationships. No output schema needed. 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% with a clear description for the single parameter ('Memory key to delete'). The tool description does not add additional parameter details beyond what the schema provides, but it mentions 'by key' which aligns. 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?

Description clearly states 'Delete a previously stored memory by key' with specific verb and resource. It distinguishes from siblings by mentioning pairing with 'remember' and 'recall', and the name itself contrasts with other tools like '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 states when to use: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also provides pairing alternatives: 'Pair with remember and recall.'

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds that it fetches the page, extracts content, and emits markdown, but no additional behavioral traits like rate limits or error handling are mentioned.

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

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

The description is three sentences long, front-loaded with the main purpose, and wastes no 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?

Given the tool's simplicity (2 parameters, no output schema), the description is complete. It explains the input, process, and output format. No missing critical information for typical use.

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

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

Schema description coverage is 100% (both url and max_links have descriptions). The description does not add meaning beyond what the schema already provides, so it meets the baseline of 3.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, fetching the page and extracting title/description/links. It distinguishes itself from sibling tools like ai_visibility_check and scan_competitor_ai_presence by focusing on file generation rather than analysis.

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

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

The description lists specific use cases (indexing a client's site, drafting for own project, auditing competitors) but does not explicitly state when not to use this tool or provide alternatives. Clear context is provided, making it easy to decide appropriate usage.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds that it lists feeds and provides filtering options, which is consistent with annotations but does not reveal additional behavioral traits beyond what annotations already convey.

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

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

The description is two sentences, front-loaded with the purpose, and contains no redundant or irrelevant information. Every sentence serves a clear function.

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 two optional parameters and no output schema, the description adequately covers purpose, return fields, usage context, and follow-up action. It is complete given the tool's complexity.

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

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

The schema description coverage is 100% (both parameters have descriptions). The description restates the filtering functionality but does not add new semantic information 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 explicitly states the tool lists curated cybersecurity feeds with fields (id, title, category, source), mentions optional filters, and suggests a follow-up action (read_feed). This clearly distinguishes it from siblings like read_feed.

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 indicates when to use the tool (list feeds, optionally filter) and points to read_feed for specific feeds. It lacks explicit when-not-to-use or alternatives, but the context is clear enough for selection among many siblings.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds value by listing return fields and indicating it's for active subscriptions, with optional inactive inclusion. No contradictions.

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

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

Two sentences, no fluff: first states action and outputs, second gives usage guidance. Efficiently 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 one optional parameter and no output schema, the description covers purpose, return fields, and when to use. Complete for the complexity level.

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 boolean parameter. Description does not add detail beyond schema, but baseline is 3 when schema is sufficient.

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

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

Description clearly states 'List the caller's active subscriptions' with specific return fields. Distinguishes from sibling tools 'subscribe' and 'unsubscribe' by explicitly stating use cases for reviewing and canceling.

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

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

Explicitly tells when to use: 'review what you're monitoring before adding more or to find an id to cancel.' Provides clear context for using this tool versus alternatives.

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

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

Discloses rate limit of 5 per identifier per day and that calls are free/no quota impact. This goes beyond the annotations, which only indicate read/write traits. 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?

Concise and well-structured: front-loads purpose, then provides usage guidelines, behavioral notes, and parameter guidance in a logical flow. No fluff, every sentence adds value.

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

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

Given the tool's complexity (3 parameters, nested object, enum), the description covers all necessary context: when to use, what to include in message, rate limits, quota impact, and team response. No output schema but not needed for a feedback tool.

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

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

Schema has 100% coverage with descriptions for each parameter. The description adds value by instructing users to describe issues in terms of Pipeworx tools/packs and not paste end-user prompts, which clarifies how to fill the 'message' field. Slight redundancy with schema's type enum descriptions prevents a 5.

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

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

The description clearly states the tool's purpose: to send feedback about bugs, missing features, data gaps, or praise. It specifies the types of feedback and distinguishes from other tools by focusing on reporting issues with Pipeworx tools/packs.

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

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

Explicitly tells when to use each feedback type: bug for wrong/stale data, feature for missing tools, data_gap for unexposed data, praise for positive experiences. Also mentions rate limits and that it doesn't count against quota, leaving no ambiguity about usage.

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

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

Annotations already declare readOnlyHint, idempotentHint. Description adds valuable context: derived from CF analytics-engine, no PII, cached 5min-1h. No contradiction.

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

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

Three sentences plus bulleted use cases. Front-loaded with core action. Every sentence adds value. Slightly verbose but still concise overall.

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-only trend tool, description covers purpose, when to use, parameter meaning, data source, caching, and return contents. No output schema, but return is clearly described. 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?

Single parameter window has enum and description in schema. Description adds meaning: shorter windows show hot trends, longer show steady-state. Schema coverage 100%, but description 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?

Description clearly states it returns top tools, packs, and call volume over a window. Three explicit use cases differentiate it from siblings like discover_tools or ask_pipeworx.

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 gives three when-to-use scenarios. Does not state when not to use, but context from siblings implies alternatives. Clear and helpful.

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

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

Annotations indicate readOnly, idempotent, openWorld. Description goes far beyond by detailing the validation logic (Jaccard similarity >0.30, placeholder filter, fill check), constraints (call with no args fails), and guidance on interpreting results (do not trade if realizable_edge_pp ≤ 0). No contradiction with annotations.

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

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

The description is well-structured with a critical requirement first, then mode explanations, details on checks, and response format. While dense, every sentence adds value. Slightly verbose but appropriate given 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?

No output schema, but the description explains the response structure (opportunities[] with fields, partition_check, fill_check), constraints, and when to use sibling tool for custom sizing. Covers all key aspects for an agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by explaining that event accepts slugs or full URLs, topic accepts seed questions, and recommending event for single-market analysis. Provides context beyond schema.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, and specifies two distinct modes (event and topic). It differentiates from sibling tools like polymarket_edges or polymarket_fill_risk by focusing on arbitrage detection.

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

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

Provides explicit guidance on when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. Warns that calling with no args fails. Mentions that cross-event catches patterns single-event misses, but does not explicitly exclude alternatives or state when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as true/false. The description adds rich behavioral context: 1h caching, detailed model families (crypto_price, news_momentum, partition_overround, concentrated_longshot), diagnostics segments, and explanation that Fed bets are excluded due to unreliable signals. No contradictions.

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

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

The description is lengthy but well-structured: front-loaded purpose, then model families, segments, knobs, and response structure. Every sentence adds value, though some mathematical details (e.g., lognormal barrier formula) could be pruned for brevity. Overall efficient 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?

With 9 parameters, no output schema, and complex internal logic, the description is thoroughly complete. It details the response structure (by_segment, fed_candidates, diagnostics), explains edge_pp_net, kelly_fraction, and the 24h-move warning, and clarifies caching. The agent can fully understand inputs, behavior, and outputs.

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

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

Schema coverage is 100% for 9 parameters, but the description significantly adds meaning beyond the schema. For example, it explains min_kelly as skipping small opportunities, slippage_pp with context on Polymarket fees and bid/ask spread, and min_liquidity with practical guidance on setting thresholds. This goes well beyond baseline.

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

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

The description clearly states the tool scans Polymarket markets to return opportunities where Pipeworx data disagrees with market price, using the specific verb 'scan' and resource 'Polymarket markets'. It distinguishes from siblings like polymarket_arbitrage by focusing on Pipeworx disagreement and the 'what should I bet on today' use case.

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

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

The description gives clear context on when to use the tool (discovery without paging hundreds of markets) and details on filtering knobs. However, it does not explicitly state when not to use it or compare it to sibling tools like polymarket_arbitrage or polymarket_edge_tracker, missing explicit exclusions.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds behavioral details like response structure (tracked[], expired[], snapshot_dates[]) and decay computation, but could be more explicit about edge value signing (negative = SELL YES). No contradictions found.

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

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

Description is dense but well-structured: purpose first, then parameter details, then full response breakdown. Every sentence adds value, though the response section could be slightly more concise. Efficient for the 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?

Given the absence of an output schema, the description provides complete coverage: explains three major response arrays (tracked, expired, snapshot_dates), their fields, and computational details (trend, decay_pp_per_day). Also notes historical bounds (60-day TTL, snapshot start time) and gaps in daily data.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context: days (lookback, default 14, max 30) and window (snapshot family, default '1wk'), which clarifies purpose beyond schema. Indicates max of 30, consistent with schema's clamp of 2-30.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It uses specific verbs ('answers', 'tracks') and distinguishes itself from sibling tools like polymarket_edges (snapshot data) and polymarket_arbitrage.

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

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

The description implies when to use (to differentiate fresh vs old edges) and provides context limits (60-day TTL, snapshot gaps). However, it does not explicitly state when not to use this tool versus alternatives, leaving some 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?

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent with the description, which adds behavioral context like walking the ladder, returning verdicts (clean|degraded|cannot_fill), and explaining how basket mode handles per-leg detail and forced directional risk. 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 essential purpose. It is well-structured with clear sections for single-market and basket modes. Every sentence serves a purpose, though minor tightening could be possible 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 modes, no output schema), the description fully covers what the tool returns (top_of_book, vwap_fill_price, slippage_pp, etc.) and includes critical warnings about partial fills and directional risk. It is complete for agent decision-making.

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

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

Input schema has 100% coverage with descriptions for all 4 parameters. The description adds extra context beyond schema: explains how side defaults differ by mode, interprets size_usd differently for single-market vs basket, and clarifies that market and event are mutually required. This adds meaningful value.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It differentiates single-market and basket modes, and the purpose is distinct from siblings like polymarket_arbitrage and polymarket_edges, which are explicitly referenced.

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

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

Explicit guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when not to use, e.g., theoretical overround on thin books not capturable, and warns about partial basket fills converting arb into 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?

Annotations indicate readOnly and idempotent, and the description adds rich behavioral detail: modes of operation, response structure (leg prices, spread array, safety fields), compatibility_warning conditions (non-equivalent bet shapes, semantically unrelated events), temporal_alignment, and skipped counters. No contradiction with annotations.

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

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

The description is well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and uses bold for key terms, aiding readability. While informative, it is somewhat lengthy and could be more concise without losing essential details.

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

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

Given the lack of output schema, the description thoroughly explains the return values: leg-by-leg prices, spread array with top_spreads_pp, safety fields (compatibility_warning, temporal_alignment, skipped counters). All aspects of the tool's behavior and output are covered, making it complete for an agent to invoke correctly.

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

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

Schema covers 100% of parameters with descriptions, but the tool description adds value by explaining the interaction between topic and explicit tickers (explicit overrides topic), listing the pre-mapped shortcuts, and providing examples. The description enhances understanding beyond the schema.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same question, distinguishing it from sibling tools like polymarket_arbitrage (which is venue-internal) and validate_claim. It specifies two distinct modes (topic shortcuts and explicit tickers) and precisely defines the resource and action.

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 tells when to use the tool (comparing same-outcome prices across venues) and when not to rely on it (most pre-mapped topics return compatibility_warning; pre-mapped does not imply tradeable). It explains the two modes and how to interpret warning fields, providing clear guidance for safe invocation.

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 non-destructive behavior. The description adds value by specifying that the tool returns normalized items with specific fields (title, link, published, summary) and supports optional keyword filtering. This provides behavioral context beyond annotations, though no extra details on rate limits or auth are given.

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

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

Two concise sentences: first states the core action and dependency, second describes return format and optional filtering. No fluff, every sentence adds value.

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

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

Despite no output schema, the description explains the return format (fields listed). It covers all parameters (via schema) and the prerequisite (list_feeds). For a read-only, idempotent tool with good annotations, the description is complete enough for an AI agent to understand how to use it.

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

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

Schema coverage is 100%, so the schema already describes parameters. The description adds context by tying the feed parameter to list_feeds and clarifying that limit defaults to 20 and query filters on title/summary. This extra semantic context justifies a score above the baseline of 3.

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

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

Clearly states the tool reads a curated cybersecurity feed by its ID, specifies the return format with fields (title, link, published, summary), and mentions the optional keyword filter. The name 'read_feed' matches the action, and the dependency on list_feeds is indicated, distinguishing it from sibling tools like list_feeds.

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 that the feed ID comes from list_feeds, providing clear prerequisite context. The optional filtering hint gives guidance on usage. However, it does not explicitly state when to avoid this tool (e.g., if you need raw feed data, use fetch_feed), so it misses a perfect score.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context: the dual mode (with/without key), scope to identifier, and partnership with other tools. No contradictions.

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

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

The description is succinct with no wasted words. Three sentences cover purpose, usage, scope, and collaboration with sibling tools. Each sentence serves a distinct purpose, and key information is front-loaded.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It explains both modes, scope, and relationships to other tools. No missing elements for effective use.

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

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

Schema coverage is 100% and the schema description already explains the parameter. The description reinforces the dual behavior (retrieve vs list) and adds contextual meaning (e.g., 'omit to list all keys'), which adds value beyond the schema. Baseline is 3 due to high coverage, but description 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?

The description clearly states the tool's function: retrieve a saved value or list all keys. It uses specific verbs ('retrieve', 'list') and identifies the resource ('values saved via remember'). It also distinguishes itself from sibling tools by naming 'remember' and 'forget' as companion 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 explicitly states when to use the tool ('Use to look up context the agent stored earlier... without re-deriving it from scratch') and provides guidance on scoping. It also mentions pairing with 'remember' and 'forget', giving clear context for 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 side effect of mark_read flagging events as read, which is a behavioral trait beyond the readOnlyHint annotation. However, the description contradicts annotations by implying a write side effect while annotations indicate read-only.

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 front-loaded purpose, then parameter details, and an alternative access method. Two sentences could be merged, but overall concise.

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

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

Given no output schema, the description adequately explains return fields, filter options, side effect, and alternative. Complete for a medium-complexity 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%, satisfying baseline. Description adds value with examples (e.g., type 'sec_8k'), explains mark_read and unread_only behavior, and clarifies limit range implied by 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 pulls fired events from the subscription feed and lists return fields (source, citation_uri, raw payload). It distinguishes from siblings by focusing on alerts and filter options, but does not explicitly contrast with similar feed tools like fetch_feed or read_feed.

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

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

Provides context that polling works fine and mentions an alternative HTTP endpoint. However, it lacks explicit guidance on when to use this tool versus siblings, and does not 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, etc. Description adds behavioral details: fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail, and `since` parameter formats.

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

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

Description is well-structured and front-loaded with example queries, but slightly lengthy; still every sentence earns its place.

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

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

Given complexity (multiple sources, fallback, parameter formats), description is complete, including return structure (changes[] grouped by source + total_changes + citation URIs). No output schema, so description covers that.

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

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

Schema description coverage is 100%, and description adds context: explains `since` formats (ISO date or relative shorthand), `type` limited to company, `value` accepts ticker or CIK.

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 provides a change feed for a company, fans out to multiple sources, and gives example queries. It distinguishes from sibling entity_profile by explicitly stating when to use that instead.

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 usage scenarios like 'What's new with X' and 'latest on Y', and explicitly says 'Use entity_profile instead when you want the static profile regardless of window.'

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 persistence behavior: scoped by identifier, 24-hour retention for anonymous, persistent for authenticated. Annotations already provide readOnlyHint=false, destructiveHint=false, idempotentHint=true; description adds value without contradiction.

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

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

Four sentences, each purposeful. Front-loaded with main use case, then usage guidance, scope details, and complementary tools. No unnecessary words.

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

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

Despite no output schema, description is complete for a simple store operation. Covers purpose, usage, scope, and pairing. Context signals (2 required params, no enums) are fully addressed.

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

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

Schema coverage 100% with descriptions for key and value. Description adds example key formats (subject_property, target_ticker) providing extra semantic clarity beyond schema.

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

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

Description clearly states the tool's purpose: save data for reuse across conversations. Verb 'save' with resource 'data' and specific context (ticker, address, preference). Distinct from siblings like '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?

Provides explicit when-to-use: when discovering something worth carrying forward. Mentions pairing with recall and forget. Lacks explicit when-not, but context is clear.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds substantial behavioral context: it reveals that each call 'cascades through several lookup endpoints internally' and replaces 2-3 manual lookups, and details the exact return format for each entity type (including citation URIs and auto-disambiguation). This goes well beyond the annotations and fully informs the agent about what the tool does internally and what it returns.

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 efficiently structured: it opens with user-facing examples, states the core purpose, then organizes details by supported type. Every sentence provides distinct value—no fluff or tautology. It is appropriately sized 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?

Despite the absence of an output schema, the description fully compensates by detailing the return values for each entity type (ticker, CIK, company name, citation URI for company; RxCUI, ingredient, brand, citation URI for drug). It covers input, behavior, and output completely, leaving no gaps for the agent.

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

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

Schema coverage is 100%, but the description enriches parameter understanding. For type, it explains what each enum value returns and how input is auto-disambiguated. For value, it gives concrete examples (ticker, CIK, name for company; brand/generic name for drug) and clarifies accepted formats. This adds significant meaning beyond the schema's simple descriptions.

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

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

The description begins with concrete natural-language examples like 'What's the ticker for…' and explicitly states the core purpose: resolve a name to the canonical identifier needed by other tools. It clearly lists supported types (company, drug) and distinguishes itself from siblings by stating 'Use FIRST whenever you have a name but need an ID.' This provides a specific verb, resource, and scope, with strong sibling differentiation.

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

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

The description gives explicit usage context: 'Use FIRST whenever you have a name but need an ID.' It also provides example queries that trigger the tool. While it does not explicitly list when not to use it or name alternative tools, the directive to use it first implies that subsequent tools (like entity_profile, compare_entities) are used after resolution. This provides clear context but lacks explicit exclusions.

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

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

Annotations already declare `readOnlyHint=true`, `idempotentHint=true`, and `destructiveHint=false`. The description adds that each entity is probed via `ai_visibility_check` and the results are ranked by score, confidence, and signal density. No contradictions; the description enhances the minimal annotation 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?

Two sentences: first states the core purpose, second explains the process and use case. No unnecessary words. The description is front-loaded and every sentence adds value.

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

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

The description covers what the tool does, how it works (internal call to `ai_visibility_check`), and what it returns (ranked list with scores). Given the absence of an output schema, this provides sufficient context. Minor missing details like error behavior or exact output format keep it from a 5.

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% — all parameters have clear descriptions that already explain the first entity as subject, models supported, etc. The description does not add new semantic meaning beyond what the schema provides, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, ranking by score. It uses specific verbs ('Compare', 'Probes', 'ranks') and distinguishes itself from siblings like `ai_visibility_check` (single entity) and `compare_entities` (likely broader comparisons).

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 use case ('competitive AI-marketing audits') and gives a concrete example. It implies that for a single entity, `ai_visibility_check` should be used instead. However, it does not list alternative tools or exclude other contexts beyond the example.

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

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

The description discloses that the tool is read-only and idempotent, consistent with annotations. It adds important behavioral details: partial failures degrade gracefully, bundlephobia's first measurement may take 5–30s, and the field sources_failed will list any timeout. No contradiction with annotations.

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

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

The description is well-structured: starts with the composite purpose, followed by usage guidance, return format, ecosystem scope, and failure behavior. Every sentence adds value with no redundancy. It is concise yet comprehensive 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?

Given no output schema, the description fully explains the return format (summary block with specific fields, advisory details, links, alternative versions). It covers failure modes (timeout, sources_failed) and ecosystem limitations. This provides complete context for the agent to understand and trust the tool's output.

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

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

Schema coverage is 100% with clear descriptions for package (accepts scoped names) and version (defaults to latest). The description enriches these by explaining the return structure (summary block with fields like is_latest, license, advisory_count, etc.) and the behavior of bundlephobia timing, which aids parameter interpretation.

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 is a composite check for npm packages, aggregating data from deps.dev and bundlephobia. It specifies the resource (npm package) and the scope (safety, popularity, size). It distinguishes from siblings like scan_competitor_ai_presence by targeting dependency evaluation.

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 advises using the tool when an agent asks about safety, popularity, or size of an npm package. It notes the limitation to NPM ecosystem v1 and directs other ecosystems to deps.dev:version directly. It also mentions graceful degradation for bundlephobia timeouts, setting expectations.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description adds value by disclosing technical details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' It also notes that passages carry offsets for verification. This provides behavioral context beyond the annotations.

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

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

The description is concise and well-structured: it opens with purpose, then usage guidance, then technical details and pairing. Every sentence serves a purpose with zero 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?

Despite lacking an output schema, the description explains that the tool returns 'top-N passages with character offsets and similarity scores.' It also covers input limits, pairing, and algorithmic details. For a 2-required-param tool, this is sufficiently complete.

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

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

Schema description coverage is 100%, but the description adds context: max 200K chars for text, examples for query, and default limit of 5. This enhances understanding beyond the schema's basic descriptions.

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

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

The description clearly states it performs semantic search inside a fetched record, specifying the verb 'search inside' and the resource (a record's text). While it mentions pairing with ask_pipeworx_grounded, it does not explicitly distinguish itself from other sibling tools like ask_pipeworx or deep_research, but the core purpose 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?

Explicitly states when to use: 'when the record is too big to cram into the prompt' and provides an alternative pattern: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear context and exclusion 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 indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: it requires authentication, creates a subscription, returns an ID, and details delivery constraints like SMS limits (10/day) and webhook auto-disable. It does not contradict annotations.

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

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

The description is thorough but front-loaded with the core purpose and return value. It efficiently covers auth, types, and delivery channels. While somewhat lengthy, every sentence serves a purpose, so it balances completeness with structure.

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

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

Given the complexity (3 parameters, nested objects, multiple types, output schema absent), the description covers return value (subscription id), auth requirements, type-specific params, and delivery channel behavior. Minor gaps like creation rate limits or idempotency implications are not addressed, but overall it is sufficiently complete.

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

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

Schema coverage is 100% and the description enriches each parameter with examples and constraints (e.g., sec_8k items, delivery webhook signing). It adds significant meaning beyond the schema definitions, especially for the nested params and delivery objects.

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 creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It distinguishes from sibling tools like list_subscriptions and unsubscribe by specifying the creation action and result.

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

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

The description provides explicit context for when to use this tool: to create a subscription for live data events. It mentions required Pipeworx OAuth account and supported types with examples. However, it does not explicitly state when not to use or guide toward alternative tools for one-off queries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: it returns category-bucketed example questions, drawn from the live catalog, and can be focused with the topic parameter. No contradictions.

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

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

The description is moderately long but front-loaded with example queries and well-structured. Each sentence adds value: usage hints, parameter explanation, and output description. Could be slightly more concise, but no wasted words.

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

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

Despite no output schema, the description adequately explains what the tool returns (category-bucketed example questions with tool+argument shapes) and when to use it. For a simple onboarding tool, it is sufficiently complete.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning by explaining the topic parameter as an optional focus area and listing possible values (finance, pharma, etc.), which are not enumerated 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 returns example questions about Pipeworx capabilities, categorized by topic, with tool and argument shapes. It includes multiple example queries and distinguishes itself as the onboarding entry point from sibling tools like ask_pipeworx.

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 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.).' This provides clear when-to-use guidance and references alternatives.

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

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

The description explains that 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts', disclosing the behavioral trait of soft deletion beyond what annotations (readOnlyHint=false, destructiveHint=false) provide. It also mentions ownership enforcement.

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 that are front-loaded with the action and ownership, then explain the behavioral effect. 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 tool with one parameter and no output schema, the description explains the deactivation behavior and links to 'recent_alerts', providing complete context for correct invocation.

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

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

The schema has 100% coverage with a clear description for parameter 'id'. The tool description does not add additional meaning beyond 'by id', so baseline 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id', specifying the verb 'cancel' and resource 'subscription'. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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

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

It states 'Ownership is enforced — you can only cancel your own subscriptions', providing clear context on when to use the tool. It does not explicitly mention alternatives but implies not to use for others' subscriptions.

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

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

Annotations already declare read-only, non-destructive, idempotent, and open-world. The description adds significant behavioral context: returns verdict categories, structured form, actual value with citation, and percent delta. It also notes the tool's v1 status and supported domain.

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

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

The description is front-loaded with clear usage examples and is well-structured. It is somewhat verbose but every sentence adds value (domain scope, return value explanation). Could be slightly more concise but remains effective.

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

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

Given the simple input schema (one required param) and no output schema, the description fully covers the tool's behavior: domain, input format, return values, and limitations. No additional context is needed for an agent to use it correctly.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by explaining the natural-language nature of the claim parameter and providing examples, going beyond the schema's minimal 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 performs natural-language claim verification against authoritative sources, listing example query patterns. It distinguishes itself from siblings by specifying it handles company-financial claims via SEC EDGAR + XBRL, and mentions it replaces multiple sequential calls.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and provides example trigger phrases. While it does not list explicit exclusions, the domain specificity (company-financial claims) and sibling differentiation provide clear guidance.

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