Food Feeds

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds transparency by noting the default model is free, Anthropic requires a BYO key, and you pay Anthropic directly. It also describes the output format, which adds behavioral context beyond annotations.

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

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

The description is two sentences long, each providing essential information without redundancy. It front-loads the main action and then specifies details. Every sentence earns its place.

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

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

Given the complexity (4 parameters, no output schema), the description fully explains what the tool does, each parameter's role, and what the output looks like (per-model scores with details and combined view). It covers all necessary context for an agent to select and 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%, so parameters are already well-documented. The description adds value by explaining defaults (workers-ai as default model), conditions for _apiKey (only needed if probing Anthropic), and clarifying the purpose of context (disambiguation). This goes beyond the schema's descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It specifies default model, optional Anthropic probing, and return structure. This distinguishes it from siblings like scan_competitor_ai_presence.

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

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

The description mentions relevant use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring), providing good context. It does not explicitly exclude other uses or compare to sibling tools, but the context is sufficient for most scenarios.

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 safe, read-only, idempotent behavior. Description adds that it returns structured answers with citation URIs, routes to many tools, and works on all tiers. 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?

Decently concise with key point front-loaded ('PREFER OVER WEB SEARCH'). Includes examples and structure. A bit lengthy but earns its length with valuable guidance.

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, annotations, and sibling tools, the description is complete: covers purpose, usage, examples, alternatives, behavioral traits, and return format. No gaps.

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

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

Parameter schema has 100% coverage with clear descriptions and aliases. Description doesn't add much beyond schema, but the schema itself is thorough. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: answering factual questions about real-world entities/events using a large set of verified sources, with specific examples. It distinguishes from siblings like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit guidance: prefer over web search, lists qualifying question types, gives examples, and explains when to step up to other tools. Covers when-not-to-use and alternatives.

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

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

Annotations already declare readOnlyHint and destructiveHint. The description adds rich behavioral context: the refusal mechanism with explicit refusal_reason values, the fetch-and-extract process, and that it costs an extra LLM call. No contradiction with annotations.

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

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

Description is fairly long but well-structured and front-loaded with key purpose and usage. Every sentence adds value. Slightly verbose in listing refusal reasons but acceptable.

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?

Complex tool with 31 siblings, high-stakes usage, no output schema. The description covers differences from sibling ask_pipeworx, refusal reasons, cost trade-off, and output format. Complete enough for an agent to decide and 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 all parameters documented as aliases for 'question'. The description mentions 'Your question in natural language' but adds no novel information beyond the schema. 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 defines it as a 'Hallucination-resistant answer mode for high-stakes reads' and explains the extraction process. It distinguishes itself from ask_pipeworx by specifying the extra LLM call cost and 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?

Explicitly states when to use ('high-stakes reads, quoted/cited answers') and when not ('prefer ask_pipeworx for casual lookups'). Provides concrete examples like financial, legal, medical lookups.

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 readOnly, idempotent, openWorld, non-destructive. Description adds crucial behaviors: low-confidence short-circuit, closed market status, illiquid wide spread warning, resolution-rule risk, resolver contract inspection guidance. These details far exceed 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 clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every sentence adds value; no redundancy. Could be slightly more concise but complexity warrants 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?

Covers all aspects: market resolution, classification, fan-out logic, response structure, safety mechanisms, edge cases (closed markets, wide spreads, resolution risk), and extraction details. Without output schema, the description fully compensates.

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

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

Schema coverage is 100% with descriptions for all 3 params. Description adds value by clarifying market input formats (slug, URL, question), depth defaults, and include_raw payload sizes.

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?

Describes a specific action: researching a Polymarket bet by pulling Pipeworx data, resolving, classifying, fanning out, and returning evidence. Distinguishes from siblings like polymarket_edges and polymarket_edge_tracker by focusing on research rather than edge tracking or 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?

Explicitly states use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides extensive fan-out examples. Lacks explicit 'when not to use' but context with sibling tools provides differentiation.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds rich behavioral context: it explains data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), off-calendar fiscal year handling, result sorting by primary metric, and return format with citation URIs. No contradictions with annotations.

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

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

The description is a single paragraph but dense with useful information, front-loading example queries. It is efficient but could benefit from bullet points or clearer separation of company vs. drug behavior. Nearly 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 complexity (two entity types, multiple data sources, sorting behavior, citation URIs), the description covers all essential aspects. No output schema exists, so the description explains the return format sufficiently. It is complete for an agent to select and invoke correctly.

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

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

Input schema covers both parameters 100% with descriptions. The description adds value by explaining what data each 'type' retrieves and the expected format of 'values' (tickers/CIKs for companies, drug names). This goes beyond the schema's basic description.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs, pulling specific financial data for companies (SEC EDGAR/XBRL) and clinical data for drugs (FAERS, FDA approvals, trials). It distinguishes from sibling tools like 'entity_profile' and explicitly mentions it replaces sequential single-pack lookups.

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

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

The description provides explicit usage examples ('compare X and Y', 'which is bigger', 'rank these companies') and states it should be preferred over sequential lookups. It does not include explicit when-not-to-use scenarios, but the context is clear.

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

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

Annotations already indicate safety profile; description adds account requirements, paid plan for 'thorough' depth, expected latency (15-60s), return format (findings packet with gaps), and honesty policy (never invented).

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

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

Front-loaded with critical caveats (account, alternatives) then details functionality; efficient for complexity but slightly long 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?

Covers prerequisites, usage boundaries, return structure, time estimate; no output schema but description sufficiently documents expected output.

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

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

Schema coverage is 100% with descriptions; description enriches by explaining depth levels numerically (quick=3, standard=5, thorough=8) and confirming natural language for question.

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 identifies it as a grounded multi-source research tool that decomposes questions and routes to parallel tools, distinct from siblings like ask_pipeworx for single lookups or live news.

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 (broad/multi-part structured questions), when not (breaking news, single lookups), and provides alternative tools (ask_pipeworx) with specific contextual cues.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds that the tool returns top-N tools with names, descriptions, and schemas—useful detail beyond annotations. However, it does not disclose additional behavioral traits like ranking criteria, response size limits, or pagination. With annotations doing most of the work, a score of 3 is appropriate.

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: two sentences that front-load purpose, followed by a usage directive. Every sentence adds value—no redundancy. It is well-structured and easy to parse quickly.

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

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

Given the tool has 6 parameters (many aliases) and no output schema, the description explains what the tool returns (tools with names, descriptions, schemas) and when to use it. It does not detail ranking or failure modes, but the provided context is sufficient for an agent to understand and invoke the tool correctly. Slightly more detail on result ranking would push to 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%, so baseline is 3. The description adds examples of queries (e.g., 'analyze housing market trends') and states that query accepts multiple aliases, which reinforces the schema but doesn't add new semantic meaning. The description includes a list of domains that hint at valid queries, providing moderate context beyond the schema.

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

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

The description clearly states that the tool finds tools by describing the data or task, and lists many specific domains. It distinguishes itself from sibling tools by explicitly positioning itself as a first-step discovery tool, saying 'Call this FIRST when you have many tools available and want to see the option set.' This is a specific verb+resource with clear scope and 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 provides explicit usage guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It implies when to use it (discovery) and indirectly when not (when you already know the tool). It could explicitly say when not to use, but the guidance is clear and actionable.

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 valuable context: USPTO patents API sunset and soft-fail behavior, news fallback chain, and the parallel call nature. 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 a single dense paragraph but is well-structured, starting with example queries, then preference over alternatives, then data sources and return fields. It is efficient but could be slightly improved with bullet points for readability.

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

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

Given the tool's complexity and lack of output schema, the description covers inputs, behavior, and output components (cik, company_name, recent_filings, fundamentals, patents, news, LEI). It mentions sorting of fundamentals and URIs for filings. While not exhaustive, it provides a solid overview.

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 coverage is 100% with descriptions for both parameters. The description adds semantic value by explaining that value can be a ticker or zero-padded CIK, that names are not supported, and that type is currently limited to 'company'. This goes beyond the schema.

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

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

The description clearly states the tool's purpose: providing a full cross-source profile of a US public company. It includes numerous example queries and lists all data sources (SEC, XBRL, USPTO, news, GLEIF) and return fields. It distinguishes itself from sibling tools like resolve_entity by specifying that names are not supported.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also instructs to use resolve_entity first if only a name is available. This provides clear when-to-use and when-not-to guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds value by explaining robustness (proxy fallback) and normalization, beyond what annotations provide. 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 concise sentences with no fluff. Front-loaded with purpose and key behavior, 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?

Tool is simple with 3 parameters. Description covers purpose, robustness, and sibling relation. Lacks details on output format or normalization specifics, but adequate for a fetch tool without output schema.

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

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

Parameter schema has 100% description coverage, so description does not need to add more. Description does not supplement parameter info, meeting 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?

Description clearly states verb 'Fetch and normalize' with specific resource 'RSS / Atom / RDF feed by URL'. Distinguishes from sibling tools like list_feeds (curated sources) and 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?

Explicitly states when to use (direct fetch) and when to use list_feeds first for curated sources. Also explains CF-robust fallback behavior, guiding usage in network-sensitive contexts.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds context about clearing sensitive data and stale context, but does not disclose additional behavioral traits (e.g., permissions, error handling).

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 action, and concise. Every word adds value with no waste.

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

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

For a simple deletion tool with one parameter and complete annotations, the description covers when to use it and the action. No output schema needed. Minor gap: missing info on return value or error behavior.

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

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

The schema has 100% coverage for the single parameter 'key' with description 'Memory key to delete.' The tool description does not add extra meaning beyond the schema.

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

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

The description clearly states the action 'Delete a previously stored memory by key,' specifying the verb, resource, and method. It mentions pairing with 'remember' and 'recall,' providing context but not explicit differentiation from sibling 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 lists three use cases: when context is stale, the task is done, or clearing sensitive data. It also suggests pairing with related tools. No explicit when-not, but the positive guidance 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?

The description adds behavioral details beyond annotations: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It confirms the read-only nature and output format, aligning with readOnlyHint and destructiveHint. However, it does not cover error handling or edge cases.

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

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

The description is a single paragraph that is well-structured and front-loaded with the main purpose. It contains no wasted sentences, though it could be slightly more concise or use bullet points for clarity. Still, it is efficient and informative.

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 2 parameters, 100% schema coverage, and no output schema, the description explains the output format ('single text blob') but does not clarify return type, encoding, or error scenarios. It is adequate but could be more complete, such as mentioning that the output is plain text or indicating failure modes.

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

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

Schema description coverage is 100%, with both parameters having descriptions. The description adds minimal extra meaning (e.g., 'Full URL', default/max for max_links) already present in the schema. No significant new semantic context is provided.

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 specifies the verb 'Generate', the resource 'llms.txt file for any URL', and distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on a specific output format. It also explains the benefit for AI crawlers.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting llms.txt for own project, and auditing a competitor. It provides clear context but does not explicitly state when not to use the tool or mention 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 safe, read-only behavior. Description adds return field names and filter options, but no additional behavioral traits like pagination or limits.

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

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

Single sentence with essential information front-loaded, no unnecessary words. Efficient and structured well.

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?

Returns fields are mentioned, parameters covered, and sibling differentiation included. Missing output schema but not needed; could mention ordering or limits.

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

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

Schema coverage is 100% so baseline is 3. Description mentions filters but doesn't add meaningful detail beyond schema descriptions.

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

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

Description clearly states action 'List' and resource 'curated food & dining feeds', and specifies returned fields. It also distinguishes from sibling 'read_feed' by mentioning parameter use.

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

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

Description explains optional filters and contrasts with 'read_feed', but does not cover all siblings like 'fetch_feed' 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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by listing the specific fields returned and mentioning that include_inactive defaults to false, but doesn't go beyond what annotations already cover regarding safety.

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

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

The description is two sentences, front-loaded with the core purpose, and every sentence adds value. No wasted words.

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

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

Given the simple tool with one optional parameter and no output schema, the description sufficiently explains the return fields and usage context. It could be improved by mentioning the optional parameter explicitly, but overall it's complete enough.

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 parameter 'include_inactive' is fully documented in the schema. The description does not add additional meaning beyond what's in the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the fields returned (id, type, params, etc.). It distinguishes from sibling tools like 'subscribe' and 'unsubscribe' by focusing on listing existing subscriptions.

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

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

The description advises using this tool to review current subscriptions before adding more or to find an ID to cancel. While it doesn't explicitly list alternatives, the context makes it clear when to use it versus creating or cancelling 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?

Beyond annotations (which indicate no read-only, idempotent, or destructive behavior), the description discloses rate limits (5/day), that feedback is read daily by the team, and that it doesn't count against tool-call quota. No contradictions with annotations.

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

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

The description is concise (5 sentences) and front-loaded with the core action and usage scenarios. Each sentence adds essential information without redundancy.

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

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

Given the tool's simplicity (3 params, enum, no output schema), the description covers all necessary aspects: purpose, usage, constraints, and rate limits. Could be slightly more explicit about the submission process, but overall complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'type' enum in context and advising specificity in 'message', but the schema itself already provides clear descriptions. Slight improvement from 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's purpose: sending feedback about broken, missing, or needed functionality. It enumerates specific use cases (bug, feature/data_gap, praise) and differentiates from siblings which focus on queries, searches, and data retrieval.

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 defines when to use each feedback type (e.g., bug for wrong/stale data, feature for missing tools). It also provides a negative instruction ('don't paste end-user prompt') and mentions rate limits and quota exemption, guiding proper usage.

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

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

Annotations already indicate readOnly, idempotent, openWorld, non-destructive. The description adds valuable context: the data is derived from CF analytics-engine, no PII, just counts, and caching varies by window (5min to 1h). This goes beyond annotations.

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

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

The description is concise, well-structured with a clear opening sentence detailing what it returns, followed by bullet-like use cases and caveats. Every sentence adds value with no redundancy.

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

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

Given the simplicity of the tool (one optional parameter, no output schema needed), the description covers the return format (top tools, packs, volume) and caching. It is complete for an agent to understand and 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?

Only one parameter (window) with 100% schema coverage and a description in the schema. The description repeats the schema's explanation but adds no new information about usage or formats. Baseline 3 is appropriate as the description does not enhance 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 that the tool returns the top tools, top packs, and total call volume over a selected window, which is a specific and unique function. It distinguishes itself from siblings like 'discover_tools' by focusing on aggregated trending data.

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

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

The description explicitly lists three use cases with numbered items (discovering hot data sources, confirming canonical tools, seeing use case alignment), providing clear guidance on when to use this tool. It also mentions caching behavior, which helps set 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 indicate read-only, open-world, idempotent, non-destructive behavior. The description adds extensive behavioral context: it walks child markets, checks ordering, computes partition_check, and details fill-check logic with live CLOB depth. It even warns when a signal is not tradable. 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 dense but well-structured: starts with a requirement, then describes modes, semantic filters, response format, and fill check. While somewhat long, every sentence carries useful information. It is front-loaded with essential usage notes. Minor redundancy could be trimmed, but overall effective.

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

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

Despite no output schema, the description details the response structure (opportunities array, partition_check object) and explains edge cases like placeholder filtering and fill-check outcomes. It covers the main behaviors needed for an agent to use the tool correctly. Some finer points (e.g., exact response field names) are inferred, but completeness is high 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 descriptions for both parameters. The description adds significant value beyond the schema: it explains each mode's purpose, provides examples of slugs and seed questions, and describes internal logic (Jaccard similarity, placeholder filters). This enriches the agent's understanding of parameter usage.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It defines two modes (event and topic) with distinct use cases and examples, making it easy for an agent to understand what the tool does and how it differs from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description explicitly requires 'event' or 'topic' and warns that calling with no args fails. It recommends 'event' for specific markets and explains cross-event mode. It also provides criteria like Jaccard similarity and placeholder filters. While it omits explicit 'when not to use' scenarios, the guidance is clear enough for correct selection.

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

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

The description thoroughly discloses behavioral traits: it is read-only (annotations confirmed), idempotent, cached for 1 hour, and has specific handling for Fed bets (excluded with reason) and empty segments (via diagnostics). No contradictions with annotations.

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

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

The description is excessively verbose, with dense technical details on model families and formulas that are unlikely to help an AI agent decide when to call the tool. It could be significantly trimmed while preserving core purpose and filter guidance.

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 the output structure (by_segment, diagnostics), special cases (Fed bets, empty segments), and filter behavior. However, it lacks a formal output schema, which is partially compensated by detailing fields like edge_pp_net and kelly_fraction, but not fully.

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

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

All parameters have schema descriptions (100% coverage), but the tool description adds valuable context, especially for min_partition_leg_kelly, explaining why min_kelly doesn't filter partition arbs. This extra meaning elevates the score above baseline.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is built for 'what should I bet on today' and distinguishes itself from siblings by focusing on edge detection rather than fill risk or specific arbitrage strategies.

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

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

The description explicitly mentions the use case ('what should I bet on today') and provides guidance on when to adjust parameters like slippage, min_liquidity, and max_spread_pp. However, it does not explicitly exclude alternatives or provide 'when not to use' instructions, which slightly lowers the score.

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

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

Beyond annotations (readOnlyHint, etc.), the description adds significant behavioral context: snapshot write-on-cache-miss causing gaps, decay computed from daily closes (not intraday), and the bounded history depth. 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 front-loaded with the core purpose and well-organized into args, response structure, and limits. It is somewhat lengthy due to needed response details, but every sentence adds value relative to the absence of an output schema.

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 fully explains the tool's functionality, response fields (tracked, expired, snapshot_dates), and constraints (TTL, decay nature). Without an output schema, this covers all necessary 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?

Schema coverage is 100%, and the description merely restates parameter purposes (lookback, default, clamp, window family) without adding new semantic nuance. 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 it provides 'edge persistence and decay telemetry' answering 'how long has this edge existed and is it shrinking?' It uses specific verbs like 'answers' and 'provides' and distinguishes from sibling tools by focusing on historical behavior rather than raw snapshots.

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

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

The description implies when to use this tool (to differentiate between fresh and old edges) and includes limits (60-day TTL, decay from daily closes). It does not explicitly name alternative tools or give 'when not to use' guidance, but the context is sufficient for most agents.

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

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

The description discloses detailed behavioral traits: walks the ladder, returns fill specifics (top_of_book, vwap_fill_price, slippage, etc.), verdict categories, and risks like forced_directional_risk. It aligns with annotations (readOnlyHint, idempotentHint, destructiveHint false) and adds context about partial basket fills converting arbs into unhedged positions. 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 structured with sections (REQUIRES, SINGLE-MARKET, BASKET, usage note) and front-loaded with the purpose. While it is relatively long (~200 words), every sentence adds necessary value given the tool's complexity. 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?

No output schema exists, so the description takes full responsibility for explaining return values. It enumerates all key outputs for both modes (top_of_book, vwap, verdict, etc.) and covers edge cases (thin_legs, forced_directional_risk). The contextual reasons for using the tool are also fully explained.

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 mode-dependent semantics for each parameter (e.g., 'side' behavior differs for single-market vs basket, 'size_usd' interpretation). This extra context justifies a 4.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, lists specific outputs, and contrasts with sibling tools like polymarket_arbitrage by positioning itself as a pre-trade risk check. The verb 'check' and resource 'edge' are specific and non-ambiguous.

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 on when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale (theoretical overround not capturable, partial fills cause directional risk) and specifies required parameters (one of market or event). No when-not-to-use statement, but the 'above ~$500' implies a threshold for necessity.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description details safety fields (compatibility_warning, temporal_alignment, skipped counters) and explains conditions when spreads are meaningless due to non-equivalent bet shapes or temporal misalignment. 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 clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core purpose. While verbose, every sentence adds value and there is no fluff.

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

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

Given no output schema, the description thoroughly explains the response fields (leg-by-leg prices, top_spreads_pp) and edge cases (compatibility warnings, temporal alignment). Three parameters are fully documented, providing a complete picture for an AI agent.

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

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

The schema has 100% description coverage for all three parameters. The description adds meaning by listing all topic shortcuts, explaining override behavior, and stating that explicitly provided tickers override topic mappings.

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 spreads between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts and explicit tickers) and explains what the response contains. This sets it apart from sibling tools like polymarket_arbitrage.

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

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

The description explains two usage modes and warns that many pre-mapped topics return compatibility warnings, guiding the user on when the tool is useful. However, it does not explicitly contrast with sibling tools like polymarket_arbitrage for intra-venue comparisons.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's burden is lower. It adds that results are normalized and lists fields, but does not mention behavior like pagination (beyond limit param), error handling, or any rate limits. The added value is moderate.

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 - the first states the core action and input, the second adds optional filter. No filler. Every sentence provides value. Highly efficient.

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

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

With no output schema, the description compensates by listing returned fields (title, link, published, summary). It also clarifies the origin of the feed id. Missing details about ordering, error states, or handling of empty results, but for a simple read tool with openWorldHint, this is adequate.

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

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

Schema coverage is 100% with descriptions for each parameter. The tool description reinforces the schema by adding context (e.g., feed id from list_feeds) and provides defaults/range for limit (1-50, default 20) and filter scope for query (over title/summary). This goes beyond the schema.

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

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

The description clearly states the verb 'Read' and the resource 'curated food & dining feed', specifies how to identify it (by id from list_feeds), and describes the output format (normalized items with fields). This differentiates it from sibling tools like fetch_feed or 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?

The description implies a prerequisite (obtain feed id from list_feeds) and mentions optional keyword filtering. However, it does not explicitly state when not to use this tool or suggest alternatives like fetch_feed for non-curated feeds. Given the sibling context, this is a minor omission.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds scoping details (anonymous IP, BYO key hash, account ID) and behavior of omitting key to list all, enriching beyond annotations without contradiction.

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

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

Three sentences pack function, use case, scoping, and pairing without fluff. Front-loaded with the core action, then specific examples and context.

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

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

For a simple tool with one optional parameter and strong annotations, the description covers purpose, usage, behavior (omitting key), scoping, and relationships to siblings. No gaps.

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

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

Schema coverage is 100% with only one parameter ('key'), and the schema itself describes omitting key to list all. The description repeats this and adds pairing context but no new semantic detail beyond schema.

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

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

The description clearly states the tool's function: retrieve a saved value or list all keys, with a specific verb and resource. It explicitly distinguishes from sibling tools 'remember' and 'forget'.

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

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

The description gives explicit when-to-use examples (look up stored context like ticker, address, research notes) and mentions scoping. It lacks explicit when-not-to-use, but the pairing with remember/forget provides good guidance.

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

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

The annotation declares readOnlyHint: true, implying no side effects, but the description states that setting mark_read:true flags events as read, which modifies state. This contradiction severely harms transparency. The description itself is honest about the behavior, but the inconsistency with annotations creates confusion.

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 remarkably concise—four short sentences front-loaded with the action verb 'Pull'. Every phrase adds value: return fields, filter options, mark_read behavior, polling compatibility, and alternative access. No wasted words.

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

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

For a read operation with 5 parameters and no output schema, the description covers the main use case: retrieving recent alerts with optional filters and read marking. It lacks explicit mention of pagination or the effect of limit, but the schema picks up those. Overall, it is sufficiently complete for the 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 description enhances schema meaning for type (e.g., 'sec_8k'), since (ISO timestamp), and mark_read (flags events as read). However, it does not elaborate on limit or unread_only, despite these being documented in the schema. Given 100% schema coverage, the added value is good but not comprehensive.

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

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

The description clearly states that the tool pulls fired events from a subscription feed and returns recent alerts. It specifies the returned fields (source, citation_uri, raw event payload), making the purpose unambiguous. However, it does not explicitly differentiate from sibling tools like fetch_feed or read_feed, which may cause confusion.

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 actionable guidance: how to filter by type and/or since, how to use mark_read to update read status, and notes that polling works fine. It also mentions an alternative non-tool access method (GET URL). However, it does not explicitly state when not to use this tool or compare it to 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?

Discloses parallel fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail. Already annotated with readOnlyHint, idempotentHint, etc., but description adds significant behavioral context.

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

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

Single paragraph front-loaded with example queries, then details mechanics and return structure. Every sentence earns its place without redundancy.

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

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

Describes return structure (changes[] grouped by source, total_changes, pipeworx:// URIs). No output schema, so this is necessary and sufficiently complete. Covers sources, fallback, and date formats.

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

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

Schema covers all parameters (100% coverage). Description adds value by explaining 'since' format (ISO date or relative shorthand like '7d', '30d') and typical monitoring value '30d' or '1m'.

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 change feed for a company over a time window, with example queries like "What's new with X". It distinguishes from sibling tool entity_profile (static profile).

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

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

Provides explicit guidance to use entity_profile instead for static profiles. Implicitly defines use cases via example queries. Could mention other siblings but not required.

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 idempotent and non-destructive. Description adds value by explaining scoping (by identifier), persistence (authenticated vs anonymous), and retention period (24 hours). 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?

Concise paragraph with clear structure: purpose first, then usage guidelines, then behavioral details. No extraneous 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 key-value storage tool with no output schema, the description adequately covers purpose, usage, and behavior. Companion tools are referenced, aiding context.

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

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

Schema already covers both parameters with examples and descriptions (100% coverage). Description adds minimal extra meaning beyond schema.

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

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

Description clearly states the tool saves data for reuse, with specific examples like 'resolved ticker' or 'user preference'. It distinguishes from sibling tools 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?

Explicitly advises when to use ('when you discover something worth carrying forward') and mentions companion tools (recall, forget). Does not explicitly state when not to use, but context is clear.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable behavioral context: it cascades through several internal lookup endpoints and auto-disambiguates company names. This explains why using it can replace multiple manual steps, which annotations alone do not 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 concise yet comprehensive. It starts with attention-grabbing examples, states the primary use case, then breaks down supported types with clear details. Every sentence serves a purpose, and there is no redundant or extraneous text.

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 moderate complexity (two entity types with multiple return fields) and the absence of an output schema, the description covers all essential information: what each type returns, accepted input formats, auto-disambiguation, and internal cascading. It is complete enough for an agent to understand the tool's behavior and output without additional documentation.

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

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

Schema coverage is 100%, but the description adds significant meaning: it details return values for each type (e.g., for company: ticker, CIK, company_name, citation URI; for drug: RxCUI, ingredient, brand, citation). It also specifies accepted input formats (ticker, CIK, name for company; brand or generic for drug). This far exceeds the schema's generic property 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 starts with concrete examples ('What's the ticker for...') and clearly states the tool resolves a name to an official identifier. It specifies the verb 'resolve' and the resource 'entity name to ID'. The purpose is distinct from siblings like 'entity_profile' or 'compare_entities' which operate on already-resolved entities.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', providing strong usage guidance. It also explains that the tool replaces 2-3 manual lookups. While it doesn't list exclusions for when not to use it, the context is clear and the directive is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds that it internally calls ai_visibility_check, ranks results, and returns a ranked list with score, confidence, and signal density per entity. This provides useful behavioral context beyond annotations.

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

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

Description is three sentences long, front-loaded with the primary action, and contains no filler. Every sentence adds value: purpose, method, use case, and output format.

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

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

Given 4 parameters with full schema descriptions, no output schema, and annotations covering safety, the description adequately specifies the output format (ranked list with score, confidence, signal density) and usage context. No gaps remain.

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

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

Input schema has 100% description coverage, so baseline is 3. Description adds value by noting that the first entity in the array is treated as the 'subject' for narrative purposes, which is not in any parameter description. This clarifies the intended usage of the entities parameter.

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

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

Description explicitly states it compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes from sibling ai_visibility_check (single entity) and compare_entities (general comparison) by specifying AI-marketing audit focus.

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

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

Description provides a concrete use case ('does Claude know about us as well as our competitors?') and context ('competitive AI-marketing audits'). It implies when to use (multiple entity comparison) but lacks explicit exclusion for single entity cases or alternatives.

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

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

The description adds significant behavioral context beyond annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list if it times out. It does not contradict any annotation (readOnlyHint, openWorldHint, etc.).

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 verbose (multiple sentences covering various aspects) but well-structured with clear sections. It front-loads the purpose and then provides details. Every sentence adds value, though it 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 no output schema, the description thoroughly explains the return format (summary block, per-advisory detail, links, alternatives) and edge cases (partial failures, timeouts). For a complex composite tool, this is remarkably complete.

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

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

Schema coverage is 100%, so the schema already describes both parameters. The description adds value by explaining that 'package' accepts scoped packages and 'version' defaults to latest. This is helpful but not extensive, warranting a score above baseline (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's purpose as a composite check for adding an npm package, combining deps.dev and bundlephobia data. It uses specific verbs ('scan', 'check') and resource ('npm dependency'), setting it apart from siblings like 'validate_claim' or 'scan_competitor_ai_presence'.

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 tells when to use the tool: when an agent asks about safety, popularity, size, or cost of adding an npm package. It also provides exclusions: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', guiding agents to alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds valuable behavioral details: embedding model (BGE-base-en), window size (500-char overlapping), character cap (200K with truncation flag), and output features (offsets for verification). 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 at ~6 sentences, front-loading the core action. Every sentence provides essential information without redundancy. The structure flows logically from purpose to usage to technical 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 3 parameters and no output schema, the description fully covers what the tool does, how to use it, and what to expect (passages with offsets). It also explains internal mechanics, making it self-contained 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?

Schema coverage is 100% with descriptions for text, query, and limit. The description adds contextual examples (SEC 10-K, article), explains query as natural language, and clarifies the text parameter's max length. This enriches understanding beyond the schema alone.

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

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

Clearly states it performs semantic search inside a fetched record, returning top passages with character offsets and similarity scores. Distinguishes itself from sibling tools by explicitly pairing with ask_pipeworx_grounded and mentioning its use case of handling large records.

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

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

Provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt'. Also mentions an alternative or complement: 'Pairs with ask_pipeworx_grounded'. This helps the agent decide when to invoke this tool versus others.

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

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

Discloses account requirement, type-specific parameters, delivery channel details including SMS cap and webhook auto-disable after 10 failures. Adds context beyond annotations (e.g., idempotentHint is not contradicted, and describes side effects like one-time webhook secret return).

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

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

Well-structured: purpose first, then requirements, types, delivery. Slightly long but every sentence adds value; justified 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?

Covers input thoroughly but lacks details on return value beyond 'subscription id' and error conditions. With no output schema, more completeness on response structure would help.

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?

100% schema coverage, but description enriches each parameter with concrete examples and constraints (e.g., phone must be verified, webhook secret returned once). Significantly adds meaning beyond the schema.

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

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

Clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This provides a specific verb+resource and distinguishes from sibling tools like 'unsubscribe' or 'list_subscriptions' by being the creation 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?

Explicitly states requirement for OAuth account and that anonymous/BYO cannot persist, guiding when to use. Provides examples of supported types and delivery channels but does not explicitly contrast with alternatives like 'unsubscribe'.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about being an onboarding entry point, returning example questions with tool+argument shapes, and the ability to call with no arguments. This goes beyond annotations.

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

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

The description is somewhat long but front-loaded with the tool's purpose and trigger phrases. Every sentence adds value, and it is well-structured, though a slightly shorter version could be equally effective.

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

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

For a simple tool with one optional parameter and no output schema, the description is remarkably complete. It explains the return format, use cases, and relationship to meta-tools, fully satisfying the agent's needs.

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 practical meaning to the 'topic' parameter by listing example values and explaining the effect of omitting it, providing more value than the schema's brief description.

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

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

The description clearly states the tool is an onboarding entry point that returns category-bucketed example questions. It uses specific verbs and distinguishes from siblings by noting its role when the agent doesn't know Pipeworx's capabilities.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you', providing clear context. It does not list exclusions, but the usage guidance is straightforward 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?

The description goes beyond annotations by explaining that the row is deactivated (not deleted) and that historical events persist. This adds behavioral context not captured by readOnlyHint (false, so mutation) or destructiveHint (false, so non-destructive). It does not disclose error handling or auth details, but the ownership enforcement and deactivation mechanism are valuable additions.

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

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

The description is two sentences, front-loading the action and immediately following with constraints and consequences. Every sentence adds necessary information without redundancy. It is optimally concise and well-structured.

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

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

For a simple tool with one parameter and no output schema, the description sufficiently covers purpose, ownership, and effect. It does not specify return value or error handling, but the idempotentHint (true) and destructiveHint (false) cover some behavioral aspects. The description is fairly complete given the tool's simplicity.

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

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

The description only mentions 'by id', while the input schema already provides a full description (uuid from subscribe). With 100% schema coverage, the baseline is 3. The description adds minimal extra value beyond reinforcing the source of the id. No further semantic enhancement is provided.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource (subscriptions for alerts). It distinguishes from sibling tools like subscribe (creation) and list_subscriptions (listing) by specifying the cancellation operation. The added nuance of deactivation versus deletion provides clarity.

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 context for when to use: to cancel a subscription. It notes ownership enforcement ('you can only cancel your own subscriptions') and that historical data remains accessible via recent_alerts. While it does not explicitly state when not to use or list all prerequisites (e.g., must have an active subscription), it provides sufficient guidance by linking the id parameter to the subscribe tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: source (SEC EDGAR + XBRL), return format (verdict withcitation), and version scope (v1). 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 thorough but not verbose, front-loading with purpose and examples. Each sentence adds value, though minor trimming could be done without loss.

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

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

Despite no output schema, the description fully explains the return values (verdict types, structured form, actual value with citation, percent delta) and domain constraints, making it complete 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% and the description adds meaningful examples of natural-language claims ('Apple's FY2024 revenue was $400 billion'), which helps the agent understand the input format beyond the schema description.

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

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

The description clearly states the tool performs natural-language claim verification against authoritative sources, with examples ('Is it true that…'), specific domain (company-financial claims for US public companies), and distinguishes it from siblings by noting 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?

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the supported domain. While it doesn't list alternatives for out-of-scope claims, the context from sibling names and the mention of replacing sequential calls provides sufficient guidance.

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