Yelp

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

Annotations already indicate readOnlyHint and idempotentHint, so the tool is safe and non-destructive. The description adds valuable details: default model is free, Anthropic requires a BYO key, and the response structure (per-model + combined). No contradictions.

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

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

The description is a single paragraph of 4 sentences, front-loaded with the core purpose. Each sentence adds distinct value (purpose, default model, output structure, use cases) with no redundancy or fluff.

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

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

For a tool with no output schema, the description provides a high-level output structure (per-model score, confidence, signals, raw_response + combined view). It covers all parameters and usage scenarios. A slight gap is the lack of detail on 'signals' or 'raw_response' format, but overall it is sufficiently complete.

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

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

Schema description coverage is 100%, with each parameter explained. The description adds meaning beyond schema by clarifying default model behavior, BYO key usage for Anthropic, and the optional context parameter's role in disambiguation.

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

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

The description clearly states the tool probes LLMs for knowledge about entities and scores visibility 0-100 per model. It uses specific verbs (probe, score) and distinguishes from sibling tools like ask_pipeworx and scan_competitor_ai_presence by focusing on multi-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 explicitly mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains default vs. BYO key models. It does not explicitly state when not to use it, but the context and sibling list provide implicit differentiation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: it routes to 4,774 tools, returns structured answers with citation URIs, and fills arguments. No contradiction with annotations.

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

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

The description is front-loaded with the key directive 'PREFER OVER WEB SEARCH'. While it is dense, every sentence adds value. Could be slightly shorter, but it's well-structured and informative.

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

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

Given the complexity of the tool (routing to thousands of sources) and the absence of an output schema, the description covers return format (structured answer with citations), usage context, and alternatives thoroughly. It is complete for an agent to understand how to invoke 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% with detailed descriptions for each parameter, including aliases for the question field. The description reinforces that the question is in natural language, adding semantic 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 uses specific verbs like 'route' and 'fill arguments' and clearly states the tool handles factual questions about structured data. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making its purpose crystal clear.

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

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

Explicitly states 'PREFER OVER WEB SEARCH' and provides detailed when-to-use and when-to-step-up guidance, including examples and specific tool names for alternatives. It also says 'START HERE for most questions' which is very helpful.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses additional behavioral traits: costs an extra LLM call, returns detailed refusal reasons, and extracts only from tool results, providing a complete picture of its 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?

The description is well-structured, front-loading the key purpose and using clear sections. However, it includes minor verbose details (e.g., exact count of tools/sources) that could be trimmed without losing value.

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

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

Despite no output schema, the description fully details the return structure and refusal reasons, covers behavioral costs, and provides usage context, making it complete for agent decision-making and invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description repeats that it accepts a natural language question but adds no new meaning beyond the schema's alias descriptions. It does not compensate further.

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

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

The description clearly states the tool's purpose as a 'Hallucination-resistant answer mode for high-stakes reads,' explaining it extracts answers only from tool results, and explicitly distinguishes it from the sibling tool 'ask_pipeworx' by adding groundedness and refusal behavior.

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 ('whenever an answer will be quoted, cited, or acted on') and when to prefer the sibling ('prefer ask_pipeworx for casual lookups'), listing specific high-stakes domains like financial verdicts and medical lookups.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds extensive behavioral context: fan-out logic per category, resolver contract, parent event extraction, news fallback handling, safety short-circuits for low confidence/closed markets, wide-spread illiquidity detection, and resolution-rule risk analysis. No contradictions with annotations.

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

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

The description is long but well-organized with labeled sections (e.g., FAN-OUT EXAMPLES, RESPONSE SHAPES). It front-loads the core purpose and usage. While every sentence adds value, the length could be slightly reduced by trimming some examples without losing critical info. Overall efficient for the complexity.

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

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

Given the tool's complexity (3 parameters, no output schema), the description is remarkably complete. It covers input handling, fan-out logic per category, response structure with specific fields, resolver match confidence, parent event extraction, news error handling, safety mechanisms, and resolution-rule risks. An agent can use it correctly without guessing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema: explains that market accepts slug/URL/question text, depth parameter controls evidence sources (quick vs thorough), and include_raw affects response size. It provides examples in the schema itself. This enriches parameter understanding.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, or question) and outputs (evidence packet + market-vs-model comparison). This distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage, which focus on different aspects.

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

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

The description explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides context on when not to rely on results (low-confidence matches, closed markets) and what to inspect (market_match_confidence, alternatives). This gives clear 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 a safe, read-only, idempotent operation. The description adds valuable behavioral context: for companies, it pulls from SEC EDGAR/XBRL and correctly handles off-calendar fiscal years; for drugs, it pulls FAERS counts, FDA approvals, trial counts. It also explains sorting by primary metric and that results include paired data with citation URIs. No contradiction with annotations.

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

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

The description is front-loaded with example queries and includes all necessary information in a structured manner. It is relatively long but every sentence adds value. Minor redundancy could be trimmed, but overall efficient.

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

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

Given the tool's complexity and lack of output schema, the description covers the essential aspects: input constraints, data sources for each type, sorting, and output format (paired data + citation URIs). It does not mention error handling or data freshness, but for a comparison tool, the coverage is adequate.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema. For the 'type' parameter, it explains that 'company' returns specific financial metrics (revenue, net income, cash, debt) and 'drug' returns adverse event counts, approval counts, and trial counts. It also clarifies the sorting behavior, which is not evident from the schema alone.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs in one parallel call. It uses specific verbs ('compare') and resources ('companies or drugs'), and distinguishes from sequential single-pack lookups by explicitly stating preference. The examples of user queries ('Compare X and Y', 'X vs Y', etc.) make 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 strong usage guidance, explicitly stating to prefer this tool over sequential single-pack lookups when comparing entities. It explains the efficiency gain (replaces 8-15 sequential lookups). However, it does not explicitly mention when not to use it or provide alternatives among siblings, though the context of comparison is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds significant context: it is not open-web search, it decomposes questions into facets, runs tools in parallel, returns a findings packet with gaps[], and takes 15-60s. This goes beyond annotations, though rate limits or quota impacts are not mentioned.

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

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

The description is relatively long but front-loaded with critical caveats (account required, when to use alternative). It is structured and each sentence adds value, though some brevity could be achieved 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?

With only 2 parameters and no output schema, the description compensates by detailing the return format (findings packet with evidence, confidence, source, gaps[]). It covers use cases, limitations, expected time, and links to authentication. This makes the tool's behavior fully understandable 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% with parameter descriptions. The description reinforces the meaning of 'depth' by specifying facet counts (quick=3, standard=5, thorough=8) and explains that 'question' should be natural language and can be broad/multi-part, adding practical nuance beyond the schema.

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

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

The description clearly states that the tool performs grounded multi-source research across Pipeworx's structured data sources, decomposing questions into facets and running tools in parallel. It explicitly distinguishes itself from open-web search and from the sibling tool ask_pipeworx, which 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?

The description provides explicit guidance on when to use this tool (broad/multi-part questions over structured data) and when not to (breaking news, current events), with clear alternatives (ask_pipeworx). It also notes account requirements and that the 'thorough' depth requires a paid plan.

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

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

Annotations already indicate safe, read-only, idempotent operations. Description adds context that results are ready to call directly with no second schema lookup, which is valuable behavioral info.

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

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

Description is front-loaded with purpose and usage, then details. Slightly lengthy but each sentence adds value; could be trimmed slightly but still concise.

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

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

No output schema, but description fully explains return value (top tools with names, descriptions, schemas, ready to call). Adequate for a discovery tool.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds minimal extra meaning beyond the schema (lists aliases and natural language usage).

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

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

The description clearly states the tool finds tools by describing data or task, listing many domains. It distinguishes from siblings by focusing on tool discovery rather than performing specific tasks.

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 instruction to call this FIRST when many tools are available, and when to use it (browse, search, discover). Provides clear context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral context: fans out across multiple sources, soft-fails on patents, returns specific fields. No contradiction; it supplements annotations well.

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

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

The description is detailed but well-structured with examples upfront. Some redundancy (e.g., repeating that names are not supported) but overall each sentence adds value. Could be slightly more concise, but still effective.

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

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

No output schema, but description comprehensively lists return fields (cik, filings, fundamentals, patents, news, LEI). Covers edge cases (names, patent sunset, soft-fail). Given tool complexity, it is complete and self-contained.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning: explains 'type' is only 'company' currently, 'value' can be ticker or zero-padded CIK, and that names are not supported, recommending resolve_entity. This adds semantic 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 provides a 'full cross-source profile of a US public company' with specific examples like 'Tell me about X', 'brief me on Tesla'. It distinguishes from sibling tools like resolve_entity and advises preference over chaining single-pack lookups.

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

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

Explicitly tells when to use (holistic view), provides alternatives (resolve_entity for names), and states 'ALWAYS PREFER over chaining single-pack' lookups. Also notes limitations like names not supported and patent sunset.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about 'clear sensitive data', improving transparency beyond annotations without contradiction.

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

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

Two sentences, front-loaded with the action, and no redundant information. Every sentence earns its place.

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

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

For a simple tool with one required parameter and no output schema, the description covers purpose, usage, and related tools completely.

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 for the 'key' parameter in the schema is adequate. The tool description does not add additional parameter details, 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 states 'Delete a previously stored memory by key.' This is a specific verb-resource pair, and the sibling tools 'remember' and 'recall' make the opposite operation clear.

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

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

Explicitly says to use when context is stale, task is done, or to clear sensitive data. Provides pairing with remember and recall, offering clear guidance on when to use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds that it fetches the page, extracts title/description/key links, and outputs standard markdown, which is consistent and transparent about the 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?

The description is concise at four sentences, front-loaded with purpose and audience, followed by process, output, and use cases. 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?

With full schema descriptions, clear annotations, and no output schema needed, the description covers all necessary aspects: purpose, process, output format, and usage context. No gaps.

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

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

Schema coverage is 100%, so the description adds no new meaning beyond what the schema already provides for url and max_links. The description's mention of 'Full URL' and 'maximum number of link entries' is present 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 generates a production-ready llms.txt file for a given URL, listing the steps (fetches, extracts, emits) and the output format. It is distinct from sibling tools like scan_competitor_ai_presence.

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

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

The description includes three explicit use cases (client indexing, personal drafting, competitor auditing), providing good context for when to use. It does not explicitly state when not to use, but the specificity of the task implies limitations.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by listing specific returned fields (rating, review count, price, etc.), providing behavioral context beyond annotations.

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

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

The description is two sentences plus an example, efficiently conveying purpose, outputs, and usage. Every sentence adds value with no fluff.

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

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

For a simple read-only tool with 2 parameters (1 required), full schema documentation, and comprehensive annotations, the description covers all necessary information including outputs and example invocation. No critical gaps.

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

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

Schema coverage is 100%, so parameters are documented. The description adds an example id value ('garaje-san-francisco') to clarify format, enhancing understanding beyond the schema.

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

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

The description clearly states the tool retrieves full details for a single Yelp business by ID/alias, specifying the verb 'Get' and resource 'business details'. It distinguishes from sibling search_businesses by focusing on retrieving details for an already-identified business.

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

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

The description implies using the ID/alias from search_businesses results and provides an example call. While it doesn't explicitly state when not to use it or compare to alternatives, the context of siblings makes usage clear.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive behavior. The description adds critical context: upstream unreliability (404 errors since mid-2026), correct id format, capped limit, and return structure (rating, text, author, timestamp). 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?

Description is information-dense with front-loaded warning and alternative suggestions. Every sentence adds value, though could be slightly tightened without losing clarity.

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

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

Despite lack of output schema, the description covers return fields, upstream issues, required input format, and parameter behavior. Complete coverage for the tool's complexity.

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

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

Schema coverage is 100%. Description adds meaning beyond schema: explains that id must be encrypted (not alias), limit is capped by Yelp upstream, _apiKey is optional with shared key default, and sort_by enum values (yelp_sort, newest).

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 gets reviews from Yelp Fusion, specifies the resource ('review snippets per business'), and distinguishes from siblings by warning about reliability issues and suggesting alternative tools (get_business, search_businesses).

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 preferring alternative tools (get_business, search_businesses) and provides precise conditions for calling get_reviews, including required id format (encrypted id, not alias) and upstream limitations.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds return fields but no further behavioral traits; consistent with annotations.

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

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

Two sentences, no fluff. Front-loads purpose and returns, then usage guidance. Perfectly concise.

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

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

For a simple list tool with one optional param and no output schema, description fully covers purpose, returns, and usage context.

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

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

Schema coverage is 100% for the single parameter. Description does not elaborate beyond schema, so baseline of 3 is appropriate.

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

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

Clearly states 'List the caller's active subscriptions' with explicit verb, resource, and scope. Distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly says when to use: 'review what you're monitoring before adding more or to find an id to cancel.' Does not cover when not to use, but sufficient for context.

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

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

Discloses that feedback is free and doesn't count against tool-call quota, and is rate-limited. This adds behavioral context beyond annotations, which only indicate non-idempotent and non-read-only nature.

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

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

Description is four sentences, front-loaded with purpose, no wasted words. Each sentence earns its place, providing clear instructions and constraints.

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

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

For a simple feedback tool with 3 params (2 required, 1 enum, nested context object), the description covers all necessary usage details. No output schema is needed; submission is straightforward.

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

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

Schema covers 100% of parameters, but description adds valuable guidance like 'describe in terms of Pipeworx tools/packs' and 'don't paste the end-user's prompt', enhancing understanding beyond schema.

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

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

The description clearly states the tool sends feedback to the Pipeworx team about bugs, features, data gaps, or praise. It uses specific verbs and resource, and is distinct from sibling tools which are query, search, and entity 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 tells when to use (bug, feature request, data gap, praise), what not to do (don't paste end-user prompt), and includes rate limits (5 per identifier per day) and cost (free, no quota). Clearly differentiates from alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. Description adds value by detailing data source (CF analytics-engine), no PII, and caching behavior (5min-1h).

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?

Extremely concise: two short paragraphs plus bullet points. Every sentence serves a purpose (definition, use cases, data source, caching). Front-loaded with main function.

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

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

For a single-parameter, read-only tool with rich annotations, the description is fully complete. Covers return values, windows, use cases, data origin, privacy, and caching. 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 window parameter with enum and description. Tool description reinforces with contextual advice ('shorter windows surface hot right now; longer show steady-state demand'), adding marginal value over schema.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a window, with specific use cases. It distinguishes itself from sibling tools like discover_tools by focusing on trending data and aggregation.

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

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

Explicitly lists three scenarios (discovering hot data sources, confirming canonical tool choice, aligning use case with agent needs) with clear context for when to use this 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 show readOnly, openWorld, idempotent, non-destructive. Description adds rich behavioral details: monotonicity violation logic, partition-sum check, semantic anchor (Jaccard similarity), partition filter, fill check against CLOB depth, and that it does not execute trades.

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

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

Well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Front-loaded with main purpose. Slightly verbose but each sentence earns its place given tool 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?

Complex tool with multiple modes and no output schema, yet description fully explains return format (opportunities[] with fields, partition_check object for event mode). Covers edge cases (low similarity, placeholder filter, realizable edge). References sibling tool for custom sizing.

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 brief descriptions. The tool description goes far beyond: explains event slug format, topic seed question, differences between modes, and the underlying logic for each. Adds substantial meaning.

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 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks'. It distinguishes three modes (no args, event, topic) and differentiates from sibling tools through detailed behavior explanation.

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 each mode: 'Call with NO args for a trending_scan... pass event for... or topic for...'. Recommends event mode, explains cross-event usage, and references sibling tool polymarket_fill_risk for custom sizing. Also states when not to trade.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description thoroughly discloses behaviors: three model families with specific computations, caching at 1h, response structure including diagnostics and Fed bets exclusion, and net-of-slippage edge calculations. No contradictions with annotations.

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

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

The description is well-structured and front-loaded, but it is verbose with highly technical details (e.g., per-sport alpha values, placeholder-slug filters). While every sentence adds value, it could be more concise for an AI agent to parse quickly.

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

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

Given the tool's complexity, rich parameter schema, and annotations, the description is complete: it details output segments, diagnostics, caching, edge computation, and knobs. It even explains why Fed bets are excluded. No missing information for an agent to use the tool effectively.

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

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

With 100% schema coverage, the description adds conceptual meaning to parameters (e.g., explaining why min_partition_leg_kelly exists and how min_kelly does not affect partition arbs). It provides context on how knobs influence output, going beyond the literal schema descriptions.

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

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

The description clearly states the tool's purpose: scanning top Polymarket markets to return opportunities where Pipeworx data disagrees with market price. It is built for 'what should I bet on today' and helps agents discover opportunities without paging through hundreds of markets, distinguishing it from siblings like polymarket_arbitrage.

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

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

The description implies usage for discovering betting opportunities but does not explicitly differentiate from alternatives like polymarket_arbitrage or when not to use it. The context of siblings is provided but no direct comparison or exclusion guidelines.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds significant detail: history bounded by 60-day TTL, decay computed from daily closes (not intraday), snapshot gaps, and response fields like trend and decay_pp_per_day. No contradictions with annotations.

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

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

The description is detailed but well-structured: a one-liner purpose, then elaboration in a question-answer format, response fields, and limits. It is front-loaded with the key question. Some redundancy could be removed, but overall concise given the tool's complexity.

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

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

Given no output schema and a complex response structure, the description fully explains all response fields (tracked, expired, snapshot_dates) with details like trend computation and lifespan. It also covers limits (TTL, decay basis) and edge cases (gaps for no scans). Very 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?

Input schema covers both parameters with descriptions (100% coverage). The description adds default values and acceptable ranges for 'days' (default 14, max 30) and 'window' (default '1wk'), and clarifies the meaning of window as snapshot family. This adds value beyond the schema.

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

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

The description clearly states the tool provides 'Edge persistence and decay telemetry' from daily snapshots, answering a specific analytical question. It distinguishes itself from sibling tools like 'polymarket_edges' by focusing on historical trends rather than current raw data.

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

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

The description implies when to use the tool via the question 'how long has this edge existed and is it shrinking?' and contrasts fresh vs old edges. However, it does not explicitly state when to use this over alternatives like polymarket_edges, though the sibling context provides indirect guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds crucial behavioral context: walking the order-book ladder, risk of partial fills, and forced directional risk. It does not contradict annotations.

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

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

The description is lengthy but well-structured, starting with purpose, then detailed mode explanations. Every sentence carries essential information. Minor redundancy (mode descriptions appear twice) but overall efficient for the complexity.

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

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

Despite no output schema, the description thoroughly enumerates return values (top_of_book, vwap_fill_price, slippage_pp, capture_ratio, thin_legs, etc.) for both modes. Combined with usage guidelines and parameter details, it provides complete understanding for agent invocation.

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

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

Schema covers all 4 parameters with descriptions (100% coverage). Description adds value by explaining default values (size_usd=1000, side auto in basket mode) and mode-specific interpretations, exceeding the baseline of 3.

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

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

The description clearly states it checks realizable vs theoretical edge against live order-book depth. It distinguishes between single-market and basket modes, and lists specific outputs (top_of_book, vwap_fill_price, etc.). This differentiates it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly instructs to use this tool before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. It explains the rationale: thin books make theoretical overround uncapturable, and partial basket fills convert arb to directional position.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds rich behavioral context: compatibility_warning conditions, temporal alignment, skipped leg counters, and the rarity of real spreads. No contradictions.

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

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

Well-structured with sections (modes, response, safety). Dense but efficient; minor redundancy in repeated 'pre-mapped ≠ tradeable' message.

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 details response format (leg prices, matched spread, safety fields). Covers edge cases and warnings comprehensively for a complex comparison tool.

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

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

Schema has 100% coverage with descriptions. Description enhances with mode details, topic list, and explanation of ticker overrides. Adds value beyond schema.

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

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

Description clearly states 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' and distinguishes two modes. It differs from sibling tools like 'polymarket_arbitrage' and 'polymarket_edges' by focusing on cross-venue comparison.

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 two-mode usage and warns about limitations via compatibility_warning and temporal_alignment. Advises that pre-mapped topics are not always tradeable. Could explicitly mention alternatives for single-venue queries.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context: retrieval vs. listing, scoping to identifier, and pairing with remember/forget. It does not contradict annotations.

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

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

The description is three efficient sentences with no fluff. It front-loads the core purpose and uses natural language examples. Every sentence adds value.

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

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

Given no output schema, the description explains return behavior (retrieve value or list keys) and scoping. It pairs with sibling tools. For a simple read-only tool with good annotations, this is sufficiently complete.

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

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

Schema coverage is 100% and the single optional parameter 'key' is well-described in the schema. The description reinforces 'omit the key argument' but adds no additional semantic 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 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument)', specifying the verb and resource. It distinguishes from siblings 'remember' and 'forget' by mentioning pairing and providing concrete use cases like user's target ticker or address.

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

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

The description explains when to use: 'to look up context the agent stored earlier... without re-deriving it from scratch'. It also notes scoping to identifier. While it doesn't explicitly list when not to use, it implies alternatives (forget for deletion) and provides clear context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds value by explaining that mark_read:true flags events as read, affecting future calls, and that polls are safe. 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 four sentences with no redundancy. The key action is front-loaded, and each sentence adds meaningful information: return fields, filtering, mark_read behavior, and alternative access method.

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

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

Despite no output schema, the description adequately describes return fields (source, citation_uri, raw payload). It covers all key parameters, explains state mutation via mark_read, and notes polling safety. For a read-only tool with full annotation coverage, this is complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context beyond the schema: explains mark_read effect, gives an example for type ('sec_8k'), and reiterates since as ISO timestamp. It does not mention limit or unread_only explicitly, but the schema already covers them.

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

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

Description starts with 'Pull fired events from your subscription feed', clearly stating the verb (Pull) and resource (fired events from subscription feed). It further details what each event carries (source, citation_uri, raw payload) and mentions filtering capabilities, distinguishing it from sibling tools like list_subscriptions or recent_changes.

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

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

The description provides explicit usage guidance: filtering by type and since, setting mark_read to track read state, and mentions that polls work fine. It also offers an alternative endpoint for scripts/dashboards. However, it does not explicitly compare to sibling tools or state when not to use this 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?

The description discloses fan-out behavior across multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO), soft-fail handling, and the parallel call nature. This adds significant value beyond the annotations (readOnlyHint, openWorldHint, etc.).

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

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

The description is front-loaded with examples and purpose, then details functionality, then provides an alternative. Every sentence adds value without unnecessary verbosity, making it concise yet information-rich.

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

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

The description fully explains the return structure (changes[] grouped by source, total_changes count, citation URIs), sources and fallback, and parameter behavior. No gaps remain for a tool with 3 required params and no output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds context: 'since' accepts ISO or relative and suggests typical values like '30d', and 'value' can be ticker or CIK. This enhances understanding beyond the schema.

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

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

The description clearly defines the tool as a change feed for a company, using specific verb phrases like 'change feed for a company' and provides example queries. It distinguishes from sibling tool 'entity_profile' by stating when to use the alternative.

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

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

The description explicitly states when to use the tool ('What's new with X', etc.) and when not to ('Use entity_profile instead when you want the static profile'), providing an explicit alternative and clear context.

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

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

Discloses key-value scoping by identifier, persistence differences (authenticated persistent vs anonymous 24h). Annotations indicate idempotent and non-destructive; description adds context without contradiction.

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

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

Four tightly written sentences with no redundancy. Front-loaded with action and purpose, then adds usage guidance and details logically.

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 memory tool (2 required params, no output schema), description covers persistence, scoping, and usage instructions. Missing potential clarification on key uniqueness behavior, but not severe.

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

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

Schema coverage is 100% with descriptions for both 'key' and 'value'. Description adds value by providing example key formats and clarifying value as any text, enhancing 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?

Clear verb 'save' and resource 'data to reuse later'. Distinguishes from siblings 'recall' and 'forget' by specifying it pairs with them. Examples of use cases (ticker, address, preference) reinforce purpose.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward'. Mentions pairing with recall and forget for full workflow. No explicit when-not, but context is sufficient.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds value by detailing internal cascading lookups and specifying the exact return fields for each entity type, going 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 well-structured with front-loaded examples, clear type breakdowns, and no superfluous 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?

Despite lacking an output schema, the description fully explains return values (including citation URIs) and internal behavior. It provides all necessary context for correct tool invocation.

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

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

Schema coverage is 100% with descriptions. The description adds significant meaning beyond the schema by explaining acceptable input formats (ticker, CIK, name for company; brand/generic for drug) and noting auto-disambiguation for company inputs.

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

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

The description clearly states the tool resolves names to canonical identifiers, provides example queries, and lists supported types (company, drug). It distinguishes from siblings by positioning it as the first tool to use when needing an ID.

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

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

Explicitly states when to use ('Use FIRST whenever you have a name but need an ID') and explains that it replaces multiple manual lookups, providing clear context for agent decision-making.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive. The description adds behavioral context: it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. This explains the internal process and return structure without contradicting annotations.

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

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

Three sentences, all essential. The first sentence states the primary purpose, the second explains the mechanism, and the third gives a concrete example. No redundant or vague phrasing.

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

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

No output schema exists, so the description correctly summarizes the return value (ranked list with score, confidence, signal density per entity). It explains the process and required parameters. However, it could include example output or data types to be fully complete for a 4-parameter tool.

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

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

Schema coverage is 100%. The description adds meaning by clarifying that the first entity in the array is treated as the 'subject' for narrative purposes and that the array should contain 2-8 entities. This goes beyond the schema's field descriptions.

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

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

The description clearly states the tool's purpose: comparing AI visibility across multiple entities side-by-side. It specifies the action (compare), the resource (AI visibility), and the output (ranked list with score, confidence, signal density). It distinguishes from the sibling tool 'ai_visibility_check' by indicating it aggregates multiple probes and ranks results.

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 a concrete use case: competitive AI-marketing audits. It implies this is for comparing multiple entities (2-8) and that the first is the 'subject'. It indirectly suggests using 'ai_visibility_check' for single entities, but does not explicitly state when not to use this 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?

Discloses behavioral traits beyond annotations: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed lists timeouts. Annotations already indicate readOnly and idempotent, and description adds critical context without contradiction.

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

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

The description is information-dense but well-structured: purpose first, then usage, behavior, limitations, and return format. Every sentence adds value, though it 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?

For a composite tool with no output schema, the description fully explains what is returned (summary block, advisories, links, alternatives), covers partial failures, and addresses timing concerns. It is complete given the complexity.

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

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

Both parameters are fully described in the input schema (100% coverage), so the description adds value by clarifying version defaults to latest and that scoped packages are accepted. This enhances understanding but the schema already does substantial work.

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 defines the tool as a composite check for npm packages covering license, advisories, bundle size, and tree-shaking. The verb 'scan_dependency' and specific resource ('npm package') are explicit, and it distinguishes itself from siblings by its composite nature.

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

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

Explicitly states when to use ('agent asks is X safe / popular / small') and provides exclusion guidance ('NPM ecosystem only in v1; other ecosystems fall under deps.dev:version directly'). This helps an AI agent choose correctly among 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=true, idempotentHint=true, and destructiveHint=false, indicating a safe, read-only operation. The description adds value by specifying the output fields (star ratings, review counts, price, etc.), which helps users understand what the tool returns.

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

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

The description is two sentences plus an example, very concise and front-loaded. The first sentence states purpose, the second lists output fields, and the example demonstrates usage. 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?

With no output schema, the description adequately explains return values by listing fields. It covers the main parameters used in search. While it doesn't detail all optional parameters, the schema compensates, making the description sufficiently complete for typical use.

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

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

Schema coverage is 100% with all parameters described. The description adds minimal meaning beyond the schema, mainly mentioning 'term' and 'location' and providing an example. This meets the baseline but does not elevate beyond it.

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

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

The description clearly states that the tool searches for local businesses and restaurants on Yelp by term and location, listing specific return fields. This distinguishes it from sibling tools like get_business or get_reviews, making its purpose unambiguous.

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

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

The description provides a clear purpose but does not explicitly guide when to use this tool over alternatives like get_business for individual businesses or get_reviews for reviews. It lacks when-not-to-use or exclusionary criteria, making usage guidance only implied.

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

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

Beyond annotations (all safe, idempotent), the description discloses technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation, and character offsets per passage. This adds significant behavioral context.

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

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

The description is information-dense yet efficient. Every sentence contributes purpose, usage, or behavioral insight. It front-loads the core function and progressively adds detail without repetition.

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 (semantic search, no output schema), the description covers all essential aspects: what it does, when to use, technical details, limitations, and integration with sibling tools. An agent can confidently select and invoke this tool based on this description.

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 already has 100% coverage with descriptions. The description adds value by providing example queries for the query parameter and restating the character limit for text, but does not introduce new meaning beyond the schema. Baseline 3, plus 1 for the examples.

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

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

The description clearly states it performs semantic search inside a fetched record, with concrete examples (SEC 10-K, article) and a specific verb+resource structure. It distinguishes itself from sibling tools by focusing on searching within already obtained text.

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

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

The description explains when to use (when the record is too large for the prompt) and mentions pairing with ask_pipeworx_grounded. It does not explicitly list when not to use or provide direct alternatives, but the context is clear enough for an agent to decide.

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 mutation (readOnlyHint=false) and idempotency (idempotentHint=true), which the description aligns with by stating it creates a subscription. The description adds rich behavioral details: account requirements, type-specific parameters, delivery channels, SMS cap (10/day), webhook auto-disable after 10 consecutive failures, and the one-time webhook secret.

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

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

The description is well-structured and front-loaded with purpose, followed by prerequisites, types, and delivery channels. Every sentence adds value without verbosity, and the use of bullet-like formatting improves 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?

Despite having no output schema, the description fully explains what the tool does, what is returned (subscription id and optionally webhook secret), prerequisites, type-specific parameters, delivery options, and limits. It is comprehensive for the tool's complexity.

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

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

Schema coverage is 100% (all parameters documented in schema). The description adds extra value beyond schema by providing concrete examples for each subscription type, explaining required vs optional params (e.g., sponsor or condition required for clinical_trial), and detailing delivery channel 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 the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It distinguishes from sibling tools like unsubscribe and list_subscriptions.

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

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

The description explicitly states when to use (proactive monitoring) and prerequisites (Pipeworx OAuth account, not anonymous/BYO). It also notes delivery channel limits, but does not explicitly compare to sibling tools such as recent_alerts.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description complements by detailing that it returns category-bucketed example questions, and the outcome of calling with no arguments vs. with a topic. No contradiction.

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

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

The description is comprehensive and front-loaded with trigger phrases, but it is relatively long. However, every sentence adds value, so it remains efficient for the amount of information conveyed.

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 single optional parameter, rich annotations, and no output schema, the description fully covers the tool's purpose, usage, and output format without gaps. It even includes example focus areas and explains the return structure.

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 description for the topic parameter. The description adds a list of focus areas and clarifies that omitting the parameter gives a cross-category spread, providing additional context beyond the schema.

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

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

The description clearly states the tool's role as an onboarding entry point for new agents, returning categorized example questions with tool+argument shapes. It mentions specific use cases like 'getting started' and distinguishes itself from siblings by being the first tool to use.

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

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

Explicitly advises to use 'FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also explains optional topic filtering and default behavior.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds critical behavioral detail: the row is deactivated (not deleted) and historical events remain available via recent_alerts. No contradiction with annotations.

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

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

The description is two sentences, concise and front-loaded. The first sentence states the core action and ownership rule; the second explains the behavioral effect. Every sentence adds value with no redundancy.

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

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

For a simple tool with one parameter, no output schema, and comprehensive annotations, the description covers purpose, ownership constraint, and soft-delete behavior. The sibling tools provide further context (subscribe, list_subscriptions). It is fully 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?

The single parameter 'id' has schema coverage of 100% and a clear description. The tool description adds contextual value by stating that the id is returned by subscribe, but the schema already provides the parameter type and description.

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

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

The description clearly states the action (cancel) and the resource (subscription by id). It effectively distinguishes from sibling tools like subscribe and list_subscriptions, leaving no ambiguity about its purpose.

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

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

The description explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), providing a clear usage constraint. However, it does not explicitly mention alternatives or when not to use it beyond ownership.

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. Description adds context: uses SEC EDGAR + XBRL, returns verdict with structured data and citation, and replaces multiple sequential calls. 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 informative but somewhat lengthy, though it front-loads key trigger phrases and purpose. It could be more concise, but every sentence adds value. Structure is logical: triggers → purpose → scope → return info → efficiency.

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

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

Given no output schema, description sufficiently explains return values (verdict, structured form, actual value, citation, delta). Parameter is fully documented. Tool complexity is moderate, and description covers context: scope, data source, and efficiency benefit.

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 the single parameter 'claim' with description and examples (100% coverage). Description reiterates and expands with additional examples and clarifies the supported claim type (company-financial for public US companies), 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?

Description uses specific verbs ('verify', 'fact check', 'confirm or refute') and clearly identifies the resource (company-financial claims via SEC EDGAR + XBRL). It distinguishes from siblings by being specialized for fact-checking, not generic search or research.

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

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

Explicitly lists natural-language triggers and states 'Use whenever the agent needs to check whether something a user said is factually correct.' It defines scope (public US company financials) and notes efficiency gains, 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.