fruityvice

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

Annotations already indicate readOnly, idempotent, non-destructive, and open-world behavior. The description adds important cost and pass-through details (Workers AI free, Anthropic BYO key, direct call to api.anthropic.com) that go 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 and front-loaded with the core function. Every sentence adds value without redundancy, fitting in a single paragraph.

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

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

Given no output schema, the description adequately details return fields per model and combined view. It covers all parameters and use cases. Missing details about error handling or timeouts are minor.

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 4 parameters with descriptions (100% coverage). The description adds value by noting the default model (Workers AI Llama-3.3-70b) and cost implications for Anthropic, which are not in the schema.

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

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

The description uses specific verbs ('Probe', 'score visibility') and identifies the resource (LLMs' knowledge of an entity). It clearly distinguishes from siblings like entity_profile or scan_competitor_ai_presence by focusing on per-model visibility scoring.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and clarifies when to use the _apiKey parameter for Anthropic. It lacks explicit when-not-to-use guidance but is sufficient for typical usage.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it returns a structured answer with stable pipeworx:// citation URIs, which is beyond annotations. However, it doesn't detail behavior when no answer is found or how routing works internally. Given annotation coverage, the description provides useful additional 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?

The description is a single paragraph but front-loaded with the key instruction 'PREFER OVER WEB SEARCH'. It lists many source categories and query examples, making it dense but not overly long. Every sentence earns its place. Could be slightly more structured (e.g., bullet points) but is effective. Score 4 for being focused and informative without waste.

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

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

Given the tool's complexity (3,745 tools, 884 sources) and no output schema, the description explains the return format (structured answer with citation URIs) and provides sufficient context for when to use it. It covers the essential 'what' and 'when'. However, it lacks explanation of error handling, rate limits, or what happens for ambiguous queries. Still, for a tool with rich annotations and schema, 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?

Input schema has 100% coverage with multiple aliases for the question parameter. The description adds value by explaining that the 'question' parameter accepts natural language and provides examples like 'current US unemployment rate'. This goes beyond the schema's minimal description, giving the agent concrete usage guidance. Baseline 3 is elevated to 4 due to explicit examples and context.

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

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

The description clearly states the tool answers factual questions using authoritative structured data, routing to 3,745 tools across 884 sources. It contrasts with web search and lists specific domains (SEC, FDA, etc.), making the purpose unmistakable. The verb 'ask' and resource 'pipeworx' are explicit, and 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?

The description explicitly says 'PREFER OVER WEB SEARCH' for questions about current or historical data from specific sources. It gives clear when-to-use examples: 'what is', 'look up', 'find', etc., and lists categories like SEC filings, FDA drug data, etc. It also implies when not to use (non-factual queries). No explicit exclusion of alternatives, but the preference is strong and context is rich.

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

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

Discloses key behaviors: extracts answers only from tool results, returns explicit refusal reasons, costs an extra LLM call. All consistent with annotations (readOnlyHint, idempotentHint, 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?

Concise yet comprehensive: covers purpose, comparison, return format, use cases, and cost tradeoff in a well-structured paragraph with no wasted words.

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

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

Despite no output schema, the description explicitly lists the return object fields and possible refusal reasons, making it fully informative 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% with all parameters described as aliases for question. The description adds context on how the question is used (routing and extraction), providing value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads'. It explains the routing process and distinguishes it from its sibling 'ask_pipeworx' by specifying the extra 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?

Explicit guidance on when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts'. Also advises to prefer 'ask_pipeworx' for casual lookups due to extra cost.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description goes far beyond by detailing fan-out patterns, response shapes, resolution contract, parent event extraction, news field fallbacks, safety mechanisms (low-confidence short-circuit, closed market handling), and cancellation rule risks. 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 very long and detailed, which is necessary for a complex tool. However, it could be more structured (e.g., bullet points or sections) to improve readability. It is front-loaded with the core purpose but becomes verbose in later parts.

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?

There is no output schema, so the description must explain return values and behavior comprehensively. It covers all major aspects: result structure, evidence keys, resolution contract, parent event, news fields, safety mechanisms, and cancellation rules. No gaps are apparent.

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 three parameters. The description adds significant value: explains market input types with examples, depth enum values, and include_raw default/effect. It also provides context on how market resolution works, which is not in the schema.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data. It specifies input types (slug, URL, question) and usage scenarios ('should I bet on X', etc.). It distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage, which have different purposes.

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

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

The description gives explicit when-to-use examples ('Use for...') and implies alternatives through sibling tool names. However, it does not explicitly say when not to use this tool versus others, leaving some inference to the agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable behavioral context: it handles off-calendar fiscal years correctly, sorts results by primary metric so 'largest' reads off the top, and provides pipeworx:// citation URIs. These details go beyond what annotations can convey and ensure the agent knows exactly what happens.

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 example queries and is well-structured, but it is somewhat verbose. Every sentence adds value, but a few could be tightened (e.g., 'Replaces 8–15 sequential lookups' is redundant with 'ALWAYS PREFER'). Still, it balances completeness with 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?

For a tool with no output schema, the description fully explains the return value: paired data with citation URIs. It also covers entity types, data sources, sorting, and edge cases like off-calendar fiscal years. Given the tool's complexity, the description provides 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?

The input schema covers 100% of the parameters with basic descriptions. The description significantly enhances meaning: for 'type', it explains what data is pulled (e.g., LATEST 10-K revenue/net income/cash/debt for company; FAERS counts for drug). For 'values', it gives concrete examples and constraints. The description makes the parameter intent crystal clear.

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 comparisons of 2–5 companies or drugs in a single call, using specific verbs like 'compare' and distinguishing from sequential lookups. It explicitly says 'ALWAYS PREFER over sequential single-pack lookups' and gives example queries, making the purpose unmistakable.

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 guidance on when to use this tool: for comparison queries like 'compare X and Y' or 'which is bigger'. It instructs to prefer this over sequential lookups, which is a strong usage directive. It also implies not to use for single-entity lookups (use entity_profile instead) by contrasting with 8–15 sequential 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?

The description adds significant behavioral context beyond annotations: decomposition into sub-questions, parallel execution, extraction of evidence with confidence scores and sources, explicit gap[] arrays for unanswered facets, and expected response time (15-60s). No contradiction with annotations (readOnlyHint=true, 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 concise yet comprehensive, fitting in 6 sentences. It front-loads the core value proposition and uses clear language 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?

Despite lacking an output schema, the description thoroughly explains the return format (structured findings packet with evidence, confidence, sources, citations, gaps). It also mentions tool count and sources, making it complete for an AI agent to understand expected outcomes.

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?

Even though schema coverage is 100%, the description enriches parameter understanding: it explains that depth:quick=3 facets, standard=5 (default), thorough=8 (paid), and that the question parameter accepts natural language and broad/multi-part queries.

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 precisely states the tool's purpose: 'Grounded multi-source research in ONE call.' It explains the decomposition, parallel routing, and extraction of evidence. It clearly differentiates from siblings like ask_pipeworx by noting that deep_research handles broad/multi-part questions while ask_pipeworx is for single 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?

Explicit usage guidance is provided: 'Use for broad or multi-part questions' with examples. It also advises when not to use it ('use ask_pipeworx for single lookups') and mentions prerequisites (Pipeworx account, paid plan for depth:thorough).

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

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

Annotations already mark the tool as readOnlyHint true and idempotentHint true. The description adds value by specifying what happens when called: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This reveals return format and a key behavioral trait (no follow-up call needed).

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 usage, then covers return details and an instruction to call first. While it packs much information into a single paragraph, every sentence adds value. It could be slightly more structured (e.g., bullet list), but it is not overly verbose.

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

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

For a discovery tool with no output schema, the description compensates well by detailing what is returned (tool names, descriptions, schemas with examples). It mentions the limit cap ('default 20, max 50') in the schema but not in the description; however, the description's coverage is adequate for an agent to understand the tool's role and output.

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

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

Schema coverage is 100% with clear descriptions on each param. The description reinforces the primary parameter 'query' with examples and explains aliases. It also mentions the limit parameter implicitly ('top-N'). The schema already provides adequate meaning, but the description adds extra context (example queries) and clarifies aliases, earning a score above baseline.

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

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

The description opens with 'Find tools by describing the data or task' — a specific verb+resource combination. It lists concrete domains (SEC filings, FDA drugs, etc.) and explicitly differentiates from sibling tools by stating 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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 you need to browse, search, look up, or discover what tools exist for:' followed by specific domains. Also includes a strong contextual signal: 'Call this FIRST...' which helps the agent decide relative to other tools like deep_research or compare_entities.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds rich behavioral details: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), lists return fields, mentions a parallel call, and notes a soft-fail for patents. 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 example queries and a strong directive ('ALWAYS PREFER'). It is information-dense but every sentence adds value. Slightly verbose but well-organized for its complexity.

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

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

Given the tool's complexity (multiple sources, many return fields, no output schema), the description is very complete. It explains all data sources, return fields, limitations (patent sunset, name not supported), and even provides URI examples for filings.

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

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

Schema description coverage is 100%, but the description adds meaning: it clarifies that 'value' accepts ticker or zero-padded CIK, not names, and that 'type' is currently limited to 'company', with future plans. It also ties 'value' to resolve_entity for names.

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 providing a full cross-source profile of a US public company in one parallel call. It uses specific verbs ('profile', 'fan out') and explicitly distinguishes itself from sibling tools like resolve_entity for name-based lookups.

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

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

The description explicitly states when to use this tool ('ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view') and when not to ('names not supported – use resolve_entity first'). It also provides alternative approaches.

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 disclose destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data, which is useful beyond the annotations. However, it does not mention error behavior for non-existent keys.

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 with two sentences, front-loading the purpose and then providing usage context. Every sentence adds value, and there is 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 tool with one parameter and no output schema, the description is complete. It covers the purpose, when to use, and related tools, providing sufficient context for an 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 input schema already describes the 'key' parameter. The description does not add additional semantic value beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key,' which is a specific verb+resource. It distinguishes from sibling tools like 'remember' and 'recall' by explicitly pairing with them and indicating the deletion action.

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

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

The description provides explicit when-to-use conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also mentions alternatives by saying 'Pair with remember and recall.'

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

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

Annotations already indicate readOnlyHint, idempotentHint, and no destructive behavior. The description adds behavioral details: fetching the page, extracting title/description/key links, and emitting standard llms.txt markdown. It also explains the output format (single text blob ready to deploy). 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 three sentences long, front-loaded with the core purpose, followed by a brief process summary, and ends with concrete use cases. Every sentence adds value with no redundant or 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?

Given the tool's simplicity (2 parameters, no output schema, annotations covering safety), the description covers purpose, process, output format, and use cases adequately. It could mention URL validation or error handling for completeness, but the provided information is sufficient for most agents.

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% for both parameters (url and max_links). The tool description does not add any additional meaning beyond what is already in the schema; it only restates the purpose briefly. Therefore, the description adds no new parameter semantics, meeting the baseline score.

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

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

The description clearly states the tool generates a production-ready llms.txt file for a given URL, specifying the output format and target AI crawlers. It lists specific use cases (indexing client sites, drafting own project, auditing competitors) which distinguishes it from sibling tools like ai_visibility_check 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 provides explicit use cases (getting a client's site indexed, drafting llms.txt, auditing competitor) that guide when to use the tool. However, it does not directly compare to sibling tools or mention when not to use it, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds no additional behavioral context (e.g., pagination, performance, permissions) beyond the purpose. 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?

Two concise sentences with the main action front-loaded. No unnecessary words.

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

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

Given output schema and full parameter descriptions, the description provides sufficient context for the tool's purpose. Could mention that it returns a list of fruits, but the output schema likely covers that.

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

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

Schema coverage is 100% with clear descriptions for all three parameters. The description repeats the parameter purpose without adding new meaning, so baseline 3 applies.

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 'Find fruits matching a nutritional range', specifying the verb, resource, and filtering criteria. Distinguishes from sibling tools (e.g., get_fruit, list_fruits) by its range-based filtering.

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?

Implies usage by describing the filtering, but does not explicitly state when to use this tool over alternatives like get_fruit or list_fruits. No when-not-to-use guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds contextual detail: returns specific nutrient values per 100g and gives examples, which is useful beyond annotations. 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?

Two sentences with front-loaded purpose and concrete examples. No extraneous content. 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 one parameter and output schema exists. Description covers what it returns and provides examples. Could mention case sensitivity or availability, but not a significant gap.

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 provides 100% coverage for the single parameter 'name' with description. Description reinforces meaning with examples but does not add new semantic details beyond the schema.

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

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

Description clearly states verb 'Get' and resource 'nutritional facts for a specific fruit', with examples of fruit names and specific nutrient fields. Distinguishes from sibling tools like list_fruits and get_by_nutrition.

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 implies usage for querying specific fruit nutrition facts but does not explicitly state when to use this tool over siblings like get_by_nutrition or list_fruits. No exclusion criteria or alternative guidance provided.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds value by detailing the return fields (name, calories, protein, etc.), which is behavioral information beyond the annotations.

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

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

The description is a single concise sentence that front-loads the essential action and result. It is efficient with no wasted words, though a slightly more structured format could improve scannability.

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 parameters and the presence of an output schema, the description adequately covers the tool's action and return data. It could mention ordering or limitations, but for a simple list tool it is sufficiently complete.

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

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

With 0 parameters and 100% schema description coverage, the description doesn't need to add parameter info. It correctly focuses on the tool's output, achieving the baseline score of 4 as per guidelines.

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: listing all available fruits with nutritional profiles. It specifies the verb 'List' and the resource 'fruits', and distinguishes from the sibling tool 'get_fruit' which handles individual fruits.

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

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

The description indicates when to use the tool (when a list of fruits is needed), but provides no guidance on when not to use it or mention of alternative tools like 'get_by_nutrition' or 'get_fruit'. The usage context is implied but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, indicating safe behavior. The description adds detail about returned fields and the optional include_inactive parameter. No contradictions.

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

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

Two sentences, no wasted words. Purpose stated first, then usage advice. Highly 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?

Given the tool's simplicity (one optional param, no output schema, strong annotations), the description fully covers purpose, return structure, and usage advice. 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?

Schema coverage is 100% and the single optional parameter 'include_inactive' is well-documented in the schema. The description does not add additional meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

Clearly states it lists the caller's active subscriptions and enumerates returned fields (id, type, params, created_at, last_fired_at, fire_count). This distinguishes it from siblings 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?

Explicitly says to use this tool 'to review what you're monitoring before adding more or to find an id to cancel.' This provides clear when-to-use guidance and differentiates from subscription management tools.

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

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

Annotations provide no safety hints (all false), so the description carries the full burden. It discloses rate limits (5 per identifier per day), cost (free), quota impact (doesn't count), and how feedback is used (team reads daily, affects roadmap). This goes well beyond what annotations provide.

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

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

The description is reasonably concise given the amount of information, with clear separation of purpose, usage conditions, and behavioral notes. Every sentence adds value, though it could be slightly trimmed without losing meaning.

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

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

Given the tool's complexity (3 parameters, nested object, enum), the description covers all necessary aspects: purpose, parameter usage, behavioral constraints, and context. No output schema is needed for a feedback tool, and the description provides complete guidance for an agent to use it correctly.

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

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

Schema coverage is 100%, but the description adds value beyond the schema by explaining message length limits (1-2 sentences, 2000 chars) and content expectations (specific tool names, not user prompts). The type enum descriptions in the schema are adequate, but the description provides additional context for when to use each type.

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: send feedback to the Pipeworx team. It lists specific feedback types (bug, feature, data_gap, praise) and provides concrete examples for each, making it easy for an agent to understand when to use this tool. It is distinct from sibling tools, which are for other purposes like querying data or discovering tools.

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

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

The description explicitly states when to use this tool: for bugs, feature requests, data gaps, or praise. It also gives negative guidance: 'don't paste the end-user's prompt' and describes the expected format (in terms of Pipeworx tools/packs). This helps the agent decide when to use this tool versus alternatives.

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

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

Annotations already mark the tool as readOnly, idempotent, and openWorld. The description adds valuable behavioral context: data source (CF analytics-engine), no PII, and caching duration (5min-1h). This goes beyond annotations and helps agents understand data freshness and privacy implications.

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

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

The description is compact, front-loading the main function, followed by use cases and technical details. Each sentence adds value. It could be slightly shortened but is well-structured and easy to parse.

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

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

Despite no output schema, the description explains the return includes 'top tools, top packs, and total call volume'. It also mentions caching behavior. For a simple tool with one input, this is sufficient context for an agent to understand what to expect.

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

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

Schema coverage is 100% with a single enum parameter. The description adds meaning beyond the enum values by explaining that shorter windows surface current hotness while longer windows show steady-state demand. This helps agents choose the appropriate window.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a recent window, using a specific verb ('returns') and resource ('Pipeworx trending'). It lists three concrete use cases, making its purpose explicit and distinct from sibling tools like 'discover_tools' or 'ask_pipeworx_grounded'.

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

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

The description provides three specific scenarios for using the tool (discovering hot data sources, confirming popular tools, aligning use case). It implies when to use but does not explicitly exclude cases or reference alternative tools. 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 declare read-only, open-world, idempotent, non-destructive. Description adds details on semantic anchor (Jaccard similarity), partition filter, fill check against live depth, and conditions that skip or nullify results. 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?

Well-structured with sections but slightly verbose; includes detailed fill check and fill_risk references that add value but could be condensed. Front-loaded with requirement and main purpose.

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 response structure (opportunities[], partition_check, fill check fields) comprehensively without output schema. Covers edge cases and references a related tool, making it complete for a complex tool.

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

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

Schema coverage is 100%, but description adds extensive meaning: explains event slug, topic as seed question, and includes examples. Also describes semantic anchor and partition filter as related constraints.

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 finds arbitrage opportunities via monotonicity violations and partition-sum checks, distinguishing two modes (event and topic) with specific use cases. It is distinct from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly requires one of `event` or `topic`, explains when to use each mode, and warns that no args fails. Provides guidance on fill check and mentions polymarket_fill_risk for custom sizing.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are fully consistent. The description adds significant behavioral context: caching at KV level, that edge_pp_net is after slippage, a 24h-move warning when market move exceeds edge, that some segments are rare-by-design, and diagnostics for empty segments. 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 long but well-organized: starts with purpose, then details three model families with formulas, output structure, knobs, diagnostics, and caching. Every sentence adds value given the tool's complexity. Minor improvement could be more bullet points or segmentation, but it is not wasteful.

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 having no output schema, the description thoroughly documents the response structure (by_segment segments, per-opportunity fields including edge_pp_net, kelly fractions, liquidity, spread, volume, 24h warning, fed candidates exclusion, diagnostics for empty segments). It covers all contexts an agent would need to invoke and interpret results.

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

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

Schema coverage is 100% (all 9 parameters have descriptions). The description adds value beyond schema by explaining the purpose of tradeable-edge knobs (min_liquidity, max_spread_pp), the behavior of min_partition_leg_kelly (partition arbs always return parent-level kelly=0), and the interaction between slippage_pp and edge ranking. This meaningfully supplements 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 'scan', resource 'Polymarket markets', and output 'opportunities where Pipeworx data disagrees with market price'. It distinguishes from sibling tools like polymarket_arbitrage by explicitly describing a different purpose: finding mispricings based on proprietary data rather than pure arbitrage.

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

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

The description explicitly states when to use: 'what should I bet on today' and 'discover opportunities without paging hundreds of markets'. It provides exclusion criteria (fed markets are excluded from ranking due to unreliable data) and explains filtering knobs (min_liquidity, max_spread_pp, etc.) and caching behavior (keyed on knobs, 1h TTL). This gives clear when-to-use and when-not-to-use guidance.

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

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

Discloses full behavior beyond annotations: returns three arrays (tracked, expired, snapshot_dates), explains computed fields (trend, decay_pp_per_day), notes gaps in snapshots due to cache-miss conditions, and clarifies decay computation. Annotations already indicate readOnly, openWorld, idempotent, non-destructive; description enriches this with operational details.

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

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

Well-structured with clear sections; purpose front-loaded, then output details, then limitations. Slightly verbose but every sentence adds value. Could be slightly more concise without losing clarity.

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

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

Given tool complexity (multiple computed fields, time-series, edge cases) and no output schema, description completely explains return values and limitations. Covers all user needs for correct invocation and interpretation.

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

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

Schema has 100% coverage of parameters. Description adds context: 'days' default 14, max 30 (consistent with schema clamp); 'window' default '1wk' and explains as snapshot family. However, does not significantly extend 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?

Defines tool as edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. Clearly distinguishes from raw snapshot tool (polymarket_edges) as the sibling list includes polymarket_edges.

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

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

Provides LIMITS section explaining history depth bounded by 60-day TTL and snapshot start time, plus decay source (daily closes not intraday). Implicitly suggests when to use (for time-series edge persistence) but doesn't explicitly state when not to use or compare 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, idempotentHint, openWorldHint, and destructiveHint false. The description adds detailed behavioral context: it walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, etc.), explains verdicts, and warns about forced directional risk. 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 well-structured with bold labels for modes, short paragraphs, and front-loaded core purpose. Every sentence is informative, though slightly verbose. Still, it earns a 4 for clarity and organization.

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 lists all returned fields (top_of_book, vwap_fill_price, shares_filled, etc.) and explains their meaning for both modes. It also covers default values, mode selection, and usage rationale. Highly complete for a complex tool with two 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 coverage is 100%, so baseline is 3. The description adds significant meaning: it explains how size_usd is interpreted differently for single-market vs basket, default side logic for basket mode, and constraints (clamp 10-1,000,000). This extra context justifies a score of 4.

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

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

Description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by positioning this as a pre-trade risk check.

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

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

Explicitly advises using this tool before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or polymarket_edges trade above $500. It explains the risk of not using it (partial basket fills converting arb into unhedged directional position), providing clear when-to-use and why.

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, openWorldHint. The description adds extensive behavioral context: explains compatibility_warning conditions, temporal_alignment, and dropped leg-pair counters, going well beyond annotations.

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

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

Well-structured with clear sections (modes, response, safety fields) and front-loaded purpose. Slightly verbose but every sentence adds value; could be tightened slightly.

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

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

No output schema, but the description fully explains the response structure: leg-by-leg prices, matched spread, safety fields like compatibility_warning and temporal_alignment, and counters. Comprehensive 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%, and the description adds rich semantics: explains how parameters interact (topic vs explicit, override behavior), provides defaults, and gives usage context for each 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?

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question, using 'verb+resource+scope' and differentiates from sibling '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?

Explicitly describes two modes ('topic' shortcuts vs explicit event identifiers), when to use each, and warns that most pre-mapped topics are not tradeable due to compatibility issues. Also emphasizes the need for temporal alignment.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about scoping to an identifier and the behavior when omitting the key (listing all keys). 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 five sentences, each adding value: purpose, examples, scoping, and pairing with siblings. No redundant information, well-structured and efficient.

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

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

For a simple retrieval tool with good annotations and schema coverage, the description is complete. It explains behavior, scoping, and pairing. Lack of output schema details is acceptable for a tool that likely returns a string or list.

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 single optional parameter 'key' already has a description stating that omitting it lists all keys. The tool description reinforces this but does not add substantial new semantics beyond the schema.

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

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

The description clearly states the tool retrieves a value saved via 'remember' or lists all keys when the key is omitted. It uses specific verbs and resources, and distinguishes itself from sibling tools like '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 provides clear use cases (e.g., looking up a target ticker or research notes) and context about scoping to an identifier. It also mentions pairing with 'remember' and 'forget', but does not explicitly exclude scenarios or list alternatives beyond siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond annotations: explains that mark_read:true flags events as read, details return fields, and notes an alternative REST endpoint. 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 (~80 words), front-loaded with purpose, and structured logically: purpose, return fields, filtering, behavioral note, polling note, alternative. No wasted sentences; every sentence adds value.

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

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

The tool has 5 parameters but no output schema. The description covers return fields, filtering, and mark_read behavior. While it omits details on limit default and unread_only, schema covers these. For a read-only tool with good annotations, it is fairly complete, but missing full output structure details prevents a 5.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning for parameters like 'type', 'since', and 'mark_read' by explaining their use and behavior. It does not repeat all param details but provides contextual value, earning 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 pulls fired events from the subscription feed, specifying return fields (source, citation_uri, raw payload). The verb 'pull' is appropriate. While it distinguishes from sibling tools like 'list_subscriptions' implicitly, it does not explicitly differentiate when to use this over others, preventing a 5.

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 polling works fine and provides an alternative REST endpoint, but lacks explicit guidance on when to use this tool versus alternatives like 'list_subscriptions' or when not to use it. The context is implied but not prescriptive, scoring a 3.

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 significant behavioral details: fanning out to multiple sources (SEC EDGAR, GDELT→GNews, USPTO), fallback logic, soft-fail for patents due to API sunset, and the return structure (grouped changes, total count, citation URIs). This goes well beyond annotation coverage.

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

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

The description is a single paragraph but is front-loaded with example queries to immediately convey purpose. It efficiently covers multiple aspects without being verbose. While it could be slightly more structured (e.g., bullet points), it remains concise and informative for its complexity.

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

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

Given the tool's complexity (multiple data sources, fallback logic, soft-fail, structured output), the description covers all necessary aspects: behavior, return format, caveats, and alternative tool. There is no output schema, so the description's explanation of the return structure is critical and well-provided.

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 schema already documents all parameters. The description provides additional context for the 'since' parameter with examples and explains the fallback behavior, but does not substantially alter the semantic understanding beyond what the schema provides. Baseline 3 is appropriate.

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

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

Description clearly states the tool provides a change feed for a company over a specified time window, with specific example queries. It also explicitly distinguishes itself from the sibling entity_profile tool, which targets static profiles. This meets the highest standard of purpose 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 usage context with example queries and a direct comparison to entity_profile, stating when to use this tool versus when to use the alternative. It also describes fallback behavior for news sources, providing clear when-to-use guidance.

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

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

Annotations already indicate write capability (readOnlyHint=false) and idempotency. Description adds important context: memory is scoped by identifier, retention policies (24 hours for anonymous), and that it's persistent for authenticated users. No contradictions.

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

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

Description is well-structured and front-loaded. Every sentence adds value, though it is slightly longer than minimal. Could be tightened but remains clear and efficient.

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

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

Given the tool's simplicity (2 params, no output schema), the description fully covers purpose, usage, scope, and persistence. 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 covers both parameters with descriptions and examples. Description does not add new semantic details 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?

Clearly states the tool's purpose: save data for later reuse across conversations. Uses specific verb 'Save' and resource 'data'. Distinguishes itself from sibling tools 'recall' and 'forget'.

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

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

Explicitly says when to use ('when you discover something worth carrying forward') and when not to (implies not for transient data). Names alternatives: 'Pair with recall to retrieve later, forget to delete.' Also explains persistence differences for authenticated vs anonymous sessions.

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, idempotent, etc.), the description discloses that each call cascades through multiple endpoints internally, auto-disambiguates inputs, and specifies exact return fields for each type, offering rich behavioral detail.

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 comprehensive and front-loaded with examples, but it is slightly verbose. However, every sentence adds value, so it earns a 4.

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

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

Given no output schema, the description covers return values thoroughly for both types, includes citation URIs, and explains internal cascading. It is nearly complete, though it does not address error handling or edge cases.

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 explains acceptable input formats (ticker, CIK, name for company; brand/generic for drug) and details the output fields, far surpassing what the schema alone provides.

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

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

The description uses specific verbs ('resolve', 'look up') and resources ('name to identifier'), provides exemplar user queries, and delineates two supported types with detailed returns, clearly distinguishing itself from sibling tools that require these identifiers as input.

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

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

Explicitly advises 'Use FIRST whenever you have a name but need an ID', clarifying priority over other tools. It also explains that the tool replaces 2-3 manual lookups, providing context for when to invoke it.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is clear. Description adds that it probes with ai_visibility_check and returns a ranked list with score, confidence, signal density. No contradictions.

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

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

Three sentences, front-loaded with main purpose, no fluff or repetition. Every sentence adds value.

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

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

Despite no output schema, description explains return structure (ranked list with score, confidence, signal density). Parameter descriptions are complete, and use case is well-articulated.

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

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

Schema coverage is 100%, so baseline is 3. Description adds semantic value by explaining that 'context' disambiguates common names and the first entity in 'entities' is treated as the subject for narrative.

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

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

Description clearly states it compares AI visibility across multiple entities, ranks them, and surfaces most/least recognized. It distinguishes from sibling tool 'ai_visibility_check' which likely handles single entities.

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

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

Explicitly states it is useful for competitive AI-marketing audits with an example question. However, it does not mention when not to use or list alternatives beyond the implied single-entity 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 indicate readOnly, idempotent, non-destructive. Description adds key behavioral traits: fan-out across two services, partial failure with graceful degradation (bundlephobia may take 5-30s, sources_failed listed). This is thorough but could mention data freshness or caching.

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

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

The description is a single paragraph that front-loads the purpose and then details sources, usage, and behavior. Every sentence adds value, though it is slightly verbose.

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 complex composite tool with no output schema, the description thoroughly explains the return content: summary block fields, advisory details, links, and alternative versions. It also covers edge cases like bundlephobia timeout and fallback.

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

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

Input schema has 100% coverage with descriptions. The description adds nuance: scoped packages accepted, version defaults to latest. This provides extra clarity 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: a composite check for adding an npm package, combining deps.dev and bundlephobia data. It distinguishes from siblings by specifying NPM ecosystem only, which differentiates it from other scanning tools.

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

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

Explicitly states when to use: for questions about safety, popularity, or cost of an npm package. Also provides guidance on when not to use: for PyPI, Maven, Cargo, Go, where deps.dev:version directly should be used.

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 embedding model (BGE-base-en), windowing (500-char overlapping), similarity metric (cosine), character cap (200K with truncation flag), and output details (offsets, similarity scores) beyond annotations which already mark it as read-only, idempotent, and non-destructive.

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

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

The description is a compact 4‑sentence paragraph, front-loading the core purpose and covering all essential aspects without any redundant or filler content.

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?

Missing explicit output schema but compensates by describing return elements (passages, offsets, scores) and pairing with another tool. Could add more structure but sufficient for a search 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 clear descriptions, but the description adds practical query examples and reiterates the 200K char limit, adding incremental value beyond the schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with concrete examples (SEC 10-K, article, tool result) and distinguishes the tool from sibling 'ask_pipeworx_grounded' by explaining how they pair together.

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

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

Explicitly advises using when 'the record is too big to cram into the prompt' and suggests an alternative workflow with 'ask_pipeworx_grounded', providing clear selection 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?

Discloses mutative nature (creates subscription), account requirements, type-specific behaviors with examples, delivery channel details including SMS cap (10/day), webhook auto-disable after 10 failures, and one-time secret return. Exceeds what annotations provide 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?

Well-structured with front-loaded purpose and account requirement, followed by type and delivery details. Slightly verbose but every sentence adds value; some redundancy could be trimmed.

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

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

For a tool with 3 params, nested objects, and no output schema, the description covers all necessary aspects: type examples, param formats, delivery options with constraints, one-time secret return, and account requirement. Complete for effective use.

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

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

Schema coverage is 100%, and description adds significant meaning: explains each type's params with concrete examples, delivery fields with validation rules and constraints, and details webhook signing. Greatly enhances the schema.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

Explicitly requires a Pipeworx OAuth account, noting that anonymous and BYO accounts cannot persist subscriptions. Provides context on when to use with examples, but does not explicitly enumerate when not to use beyond account restrictions.

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 cover safety (read-only, idempotent). Description adds details: returns live catalog examples, category buckets, and argument shapes. 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?

Efficiently uses ~100 words with front-loaded purpose. Each sentence adds value without redundancy.

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

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

No output schema, but description fully explains what is returned (categorized examples with tool shapes). Covers usage scenarios and scope comprehensively.

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

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

Schema covers 100% with one optional param. Description adds meaning by explaining topic focus areas and behavior when omitted (full spread).

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

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

Clearly states it returns example questions categorized by topics, with tool+argument shapes. Distinguishes itself as the onboarding entry point 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?

Explicitly says to use first when unaware of Pipeworx capabilities or to learn meta-tools. Provides guidance on calling with or without topic argument.

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 that the row is deactivated (not deleted) and historical events remain available. This adds value beyond annotations which already indicate nondestructive, idempotent behavior.

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

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

Two sentences with no fluff. Purpose is front-loaded and each sentence adds information.

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

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

Given simple single-parameter tool with full schema coverage and informative annotations, the description covers key behavioral nuances (ownership, deactivation) adequately.

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 description provides only minimal context beyond schema (e.g., id format). Does not add extra semantic details.

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

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

Clearly states the action (cancel) and resource (subscription). Differentiates from siblings like subscribe and list_subscriptions.

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

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

Explicitly states ownership enforcement, guiding when to use (own subscriptions) and when not (others' subscriptions).

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds significant behavioral context: it returns a verdict with multiple outcomes, extracted structure, actual value with citation, and percent delta. It also explains it's a composite tool replacing multiple calls, going beyond annotations.

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

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

The description is slightly long but front-loaded with key phrases and examples. Every sentence adds value, though a bit more conciseness could be achieved. It is 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?

Without an output schema, the description fully explains return values: verdict types, structured form, citation, and delta. It also covers scope and limitations, making it complete for this tool's complexity.

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

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

Schema coverage is 100% with the 'claim' parameter described. The description enriches the parameter meaning with natural-language examples and scope clarification (company-financial claims), adding value beyond the schema.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with specific examples like 'Is it true that…' and 'fact check'. It distinguishes itself from sibling tools by noting it replaces 4-6 sequential calls, highlighting its unique value.

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 domain (company-financial claims). It does not provide explicit exclusions or alternatives for non-financial claims, 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.