Cnpj Br

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint. The description adds key behavioral details: default model is free, Anthropic requires BYO key and is paid directly, returns per-model structure with score, confidence, signals, raw_response, plus combined view. No contradictions with annotations.

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

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

The description is three sentences, each adding distinct value. First sentence states core function and default. Second explains optional Anthropic key. Third describes return format and use cases. No wasted words.

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

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

Given the annotations and schema, the description is fully complete. It covers purpose, parameters, usage, and return format. No output schema exists, but the description compensates by listing the per-model fields (score, confidence, signals, raw_response) and combined view. Sibling tools are diverse, and this description uniquely positions the 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%. The description adds practical context: 'Default model is Workers AI Llama-3.3-70b (free)', '_apiKey only needed if anthropic is in models', and explains the context parameter helps disambiguate. This goes beyond the schema's minimal 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 is specific: 'Probe one or more LLMs for what they know... and score visibility (0-100)'. It clearly identifies the action (probe), resource (LLMs), and outcome (score). It also differentiates from siblings by specifying the unique function of AI visibility scoring, unlike other tools such as ask_pipeworx or deep_research.

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

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

The description explicitly states use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It also explains when to use the optional _apiKey (for Anthropic) and default model (workers-ai free). While it doesn't explicitly say when not to use, the context is clear enough.

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

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

Annotations cover readOnly, openWorld, idempotent hints. Description adds that it returns structured answers with pipeworx:// citation URIs, fills arguments, and that it is a single fast call working on every tier. This enriches behavioral understanding 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 long (over 150 words) but well front-loaded with key directives. It includes many examples and guidance; however, some sentences could be merged or removed without losing essential information.

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

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

Given the tool's complexity (routing among thousands of sources), the description fully covers what it does, when to use it, alternatives, examples, and output format (structured answer with citations). No gaps are apparent.

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

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

Schema coverage is 100% with descriptions for all 6 parameters (question and aliases). The description's parameter info ('Your question or request in natural language') adds no significant meaning beyond the schema's own descriptions. 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 it routes questions to 5,011 tools across 1,319 verified sources, clearly specifying the verb 'routes' and the resource (structured data). It distinguishes from sibling tools like web search, ask_pipeworx_grounded, and deep_research.

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

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

Explicitly states 'PREFER OVER WEB SEARCH' and provides when-to-use: for factual questions about real-world entities. It also lists when to step up to alternative tools, with examples. No usage scenario is left ambiguous.

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. Description adds valuable behavioral context: experimental edge, source-preference ranking behavior, fallback to nothing, and full functional router.

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

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

Front-loaded with purpose and key differentiators. Some technical details could be trimmed, but overall structure is clear and efficient.

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

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

Given complexity of beta features and routing changes, description covers purpose, usage, behavior, and comparison to stable. No output schema, but mentions same response shape, sufficient 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 description coverage is 100% with detailed descriptions for all parameters. Description does not add parameter-specific semantics beyond what schema provides, meeting baseline.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx with identical routing capabilities but improved source-preference ranking. It uses specific verbs ('use', 'compare') and distinguishes from the stable ask_pipeworx sibling.

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

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

States to use it exactly like ask_pipeworx when wanting the newest routing, and mentions comparison with stable router for merges. Implicitly suggests alternative (stable router) but no explicit when-not.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds detailed behavioral context: exact refusal reasons, extra LLM call cost, and that it selects from 5,011 tools across 1,319 sources. However, no mention of rate limits or authentication needs, keeping score at 4.

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 paragraphs, front-loaded with key purpose. Every sentence adds value: refusal reasons, use cases, cost comparison. No fluff or redundancy. Exceptionally structured for quick agent parsing.

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

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

Despite no output schema, the description fully explains return format {answer, evidence, confidence, source, fetched_at, refusal_reason} and all possible refusal reasons. Covers process, source scope, and cost trade-off. Complete for tool invocation understanding.

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

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

Schema coverage is 100% with descriptions for all 6 aliases. The description does not add meaning beyond the schema, only reiterating 'Your question in natural language.' Baseline 3 is appropriate as schema carries the burden.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It specifies verb (answer), resource (tool results), and distinguishes from sibling 'ask_pipeworx' by explaining the extra verification step and refusal mechanism.

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

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

Explicit usage guidance: use when answer will be quoted/cited/acted on and agent must not invent facts; prefer ask_pipeworx for casual lookups. This provides clear when-to-use and when-not-to-use context with 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?

Disclosures far beyond annotations: fan-out logic, resolver contract, edge cases (low confidence, closed markets, wide spreads), and resolution-rule risk. No contradiction.

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

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

Very verbose and unstructured; multiple paragraphs could be condensed. Important details are present but overly lengthy.

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

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

Extremely thorough given no output schema; covers input, process, response shapes, edge cases, and safety mechanisms.

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

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

Schema coverage is 100% but description adds significant meaning: market input formats, default depth, include_raw recommendation, and 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?

Clearly states it researches Polymarket bets, gives specific use cases ('should I bet on X'), and distinguishes from sibling tools like polymarket_edges.

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

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

Explicitly says when to use (bet decisions, data questions) and provides examples; does not explicitly mention alternatives 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 declare readOnlyHint, idempotentHint, and destructiveHint false, so the description's core behavior (querying a public registry) is consistent. The description adds value by naming the data source (Receita Federal) and listing the returned fields (legal name, registration status, partner list, etc.), which helps the agent understand what to expect.

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: the first sentence clearly states the purpose and lists the outputs; the second provides an example invocation. Every word is necessary and no information is repeated. The structure is front-loaded with the main action.

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

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

Given the tool's simplicity (one parameter, no output schema, clear annotations), the description is fully self-contained. It tells the agent what the tool does, what data it returns, how to format the input, and provides a concrete example. There are no gaps in context needed for correct invocation.

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

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

Schema coverage is 100% for the single 'cnpj' parameter. The description goes beyond the schema by clarifying that punctuation is acceptable, providing an example of both formats ('33.683.111/0002-80' and '33683111000280'), and showing a complete call example. This adds practical guidance for the agent.

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: 'Look up a Brazilian company in the CNPJ registry.' It specifies the verb ('look up') and resource ('CNPJ registry'), lists the data returned, and distinguishes it from sibling tools that cover broader research (e.g., deep_research) or other entity types.

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 positions the tool as 'the primary KYB / due-diligence check for any Brazil company,' providing clear context for when to use it. It also includes an example call and format guidance. However, it does not explicitly mention when not to use it or suggest alternatives, missing an opportunity to further guide selection.

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

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

Beyond annotations (readOnlyHint, etc.), description adds off-calendar fiscal year handling, sorted results by primary metric, and return of paired data with citation URIs. No contradictions with annotations.

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

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

Single paragraph, front-loaded with examples. Every sentence adds value, though could be slightly more concise. Still efficient and well-structured.

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

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

No output schema, but description explains return format (paired data + citation URIs) and sorting. Covers both entity types thoroughly. Complete for the complexity of the tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining what data each type ('company' vs 'drug') pulls and the expected input formats (tickers/CIKs vs drug names). Slight enrichment 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 performs side-by-side comparisons of 2–5 companies or drugs, specifying data sources (SEC EDGAR for companies, FAERS for drugs) and metrics. It distinguishes from sequential single-pack lookups by noting it replaces 8–15 sequential calls.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides natural language triggers like 'compare X and Y' or 'which is bigger'. Although it doesn't state when not to use, the guidance is strong and clear.

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

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

The description adds significant behavioral details beyond annotations: account requirement, structured data vs. open web, parallel decomposition, gap reporting, contradiction scanning, hop field, citation URIs, and performance expectations. No contradiction with annotations.

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

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

The description is lengthy but well-structured, starting with critical account/alternative info, then core functionality, depth details, and return format. Each sentence adds value, though slightly verbose for a brief tool.

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

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

Despite no output schema, the description fully explains the return packet (evidence, confidence, source, citation, gaps, contradictions, hop field) and excerpting behavior. It also covers edge cases like empty gaps for non-catalog topics.

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% (both parameters described). The description adds meaning by elaborating on the depth parameter's behavior (number of facets, hops, gap recovery) and explaining that questions can be broad. This goes beyond the schema's enum 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: multi-source structured research in one call, decomposing questions into facets and routing to thousands of tools in parallel. It distinguishes itself from open-web search and sibling tools like ask_pipeworx.

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

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

Explicitly tells when to use this tool vs. ask_pipeworx: for single lookups, breaking news, or without an account, use ask_pipeworx. Also mentions account requirements and depth 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, idempotentHint, and destructiveHint=false. The description adds value by explaining the return format (top-N tools with schemas, ready to call) and the no-second-lookup behavior, which goes beyond annotation hints. 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 a single paragraph that front-loads the purpose. It is informative without being verbose, though it could be slightly more compact. All sentences contribute 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 explains what the tool returns (top-N tools with names, descriptions, full schemas, curated examples) and that results are call-ready. It also covers usage context and parameter aliases, making it complete for a discovery tool.

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

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

Schema coverage is 100% with descriptions for all 6 parameters (though most are aliases). The description adds context about accepting natural language and lists example values, but does not significantly enhance understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many example domains (SEC filings, financials, FDA drugs, etc.), making the scope explicit. This differentiates it from sibling tools like 'deep_research' or 'ask_pipeworx' which serve different purposes.

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

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

Explicit guidance given: 'Call this FIRST when you have many tools available and want to see the option set.' This tells both when and why to use this tool, and implies not to use it when you need a direct answer.

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

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

The description discloses detailed behavioral traits—that it fans out across multiple sources, returns specific fields (cik, filings with URIs, fundamentals sorted), and handles patent API failure gracefully. This adds substantial value beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) without contradicting them.

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

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

The description is relatively long but well-structured, front-loading with example queries and core purpose. 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?

Given the tool's complexity and lack of output schema, the description is complete: it lists all returned components, explains data sources, notes the patents status, and provides usage constraints. This fully prepares an agent to invoke the tool correctly.

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

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

The description adds meaningful context to the parameters: type is limited to 'company', value must be ticker or CIK (names not supported), and recommends resolve_entity for names. Since schema coverage is 100%, this is above the baseline 3.

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

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

The description clearly defines the tool as providing a full cross-source profile of a US public company in one call, with specific example queries. It distinguishes itself from sibling tools like resolve_entity and explicitly recommends when to prefer it over chaining.

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 (holistic profile requests) and when not to (when only a name is available, use resolve_entity first). It also notes limitations like the patents API sunset and names not supported.

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 by specifying 'previously stored' and mentioning sensitive data, 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 concise sentences front-load the purpose and usage guidelines, with no superfluous words.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage, and relationships; annotations cover the behavioral aspects adequately.

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

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

Schema coverage is 100% and already describes the 'key' parameter as 'Memory key to delete'. The description adds no further meaning beyond restating 'by key'.

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

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

The description uses a specific verb ('Delete') and resource ('memory by key'), and distinguishes itself from siblings by naming 'remember' and 'recall' as companion tools.

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

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

It provides explicit use cases (stale context, task done, clear sensitive data) and suggests pairing with related tools, offering clear when-to-use guidance without explicitly stating when not to use.

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

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

Annotations declare readOnlyHint, idempotentHint, openWorldHint. The description adds behavioral detail: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This explains the process beyond annotations, though it omits potential failure cases or response format.

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

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

The description is three sentences, front-loaded with the core action and purpose. Every sentence adds value: action, output format, and use cases. No redundant or vague wording.

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 two parameters, rich annotations, and no output schema, the description covers purpose, usage, output format, and parameter defaults. It does not address error handling, rate limits, or site complexity, but for a straightforward generation tool, it is adequately complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by stating the default of 25 for `max_links` (not in schema) and reinforcing the 'Full URL' requirement for `url`. This extra context justifies a 4.

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

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

The description clearly states the tool generates an llms.txt file for a given URL, specifying the output format and listing concrete use cases (client indexing, personal project, competitor audit). It distinguishes from siblings like `scan_competitor_ai_presence` by focusing on the specific llms.txt artifact.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting your own llms.txt, or auditing a competitor. While it doesn't state when not to use or directly name alternatives, the listed scenarios give clear guidance for when to invoke the tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds context about return fields and parameter behavior (include_inactive). No contradictions, and adds value beyond annotations.

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

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

Two sentences, front-loaded with purpose and return details. Every sentence serves a purpose. 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?

Despite no output schema, description lists all return fields. For a simple list tool with one optional parameter, the description is complete and provides sufficient 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% (one boolean parameter). Description mentions 'include_inactive' and default false, which mirrors schema. No additional semantics added beyond what schema provides. Baseline 3 is appropriate.

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

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

Description clearly states 'List the caller's active subscriptions' and enumerates return fields (id, type, params, created_at, last_fired_at, fire_count). It distinguishes from siblings like subscribe/unsubscribe by explicitly naming the action and resource.

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

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

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use this tool and implies alternatives (e.g., subscribe for adding).

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?

While annotations are all false (no hints), the description provides critical behavioral details: rate-limited to 5 per day, free, does not count against tool-call quota, and specifies not to paste end-user prompts. This goes beyond annotations and informs the agent about side effects and restrictions.

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

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

The description is concise and well-structured: first sentence states purpose, followed by specific use cases, then guidance on message content, and finally constraints. 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?

Despite having no output schema, the description is complete enough for an agent to use the tool correctly. It covers what it does, when to use it, how to format the input, and what constraints apply. The agent can confidently invoke this tool.

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

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

Schema coverage is 100%, so parameters are well-documented. The description adds extra guidance on message format ('Be specific', '1-2 sentences typical') and provides real-world context for the 'type' enum (e.g., bug = something broke). This enhances understanding beyond 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: sending feedback to Pipeworx about bugs, missing features, data gaps, or praise. It distinguishes itself from sibling tools by focusing solely on feedback submission, not data retrieval or analysis.

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

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

The description explicitly tells when to use the tool: for bug reports, feature/data gap requests, or praise. It also includes constraints like rate limits (5 per identifier per day) and cost (free, not counted against quota), helping the agent decide appropriate usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: data source (CF analytics-engine), no PII, caching behavior (5min-1h). No contradiction with annotations.

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

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

Description is about 6 sentences, front-loaded with core output, and uses bullet-like enumeration for use cases. Efficient and clear, though some redundancy (window info appears both in schema and description).

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

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

Covers output, data source, caching, privacy, and use cases. However, lacks detail about the return format (e.g., structure of top tools and packs). Without an output schema, the description should provide more specifics on the returned data shape.

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 detailed description for the window parameter. The main description adds minimal extra meaning beyond the schema, restating the same enum values and window context. Baseline 3 is appropriate as schema does the heavy lifting.

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

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

Clearly states the tool returns top tools, top packs, and total call volume over a specified window. Verb 'returns' and resource are specific, and the tool is distinct from siblings like ask_pipeworx which are question-answering.

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 specific use cases (discovering hot data sources, confirming canonical tools, aligning use cases). Mentions window implications. Does not explicitly state when not to use or name alternatives, but the given guidance is clear and actionable.

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

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

Discloses detailed behavior: monotonicity checks, partition-sum, Jaccard similarity filter, placeholder filter, fill check with realizable edge. No contradiction with annotations (readOnlyHint, idempotentHint).

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

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

Long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds unique value; 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?

Fully explains inputs, modes, internal logic, response structure (opportunities array with fields), and fill-check behavior. No output schema, but description compensates thoroughly.

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 have schema descriptions (100% coverage). The description adds rich context about mode behavior, examples, and internal logic beyond the schema.

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

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

Clearly states verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' Distinct from siblings like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly describes when to use each mode (no args for trending, event for specific market, topic for cross-event) and provides examples of slugs and 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?

The description is highly transparent, detailing the response structure (by_segment, diagnostics), the behavior of parameter knobs, and caching ('Cached 1h at the KV level'). This adds substantial value beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), with 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 verbose (nearly 600 words) and front-loads the core purpose but then goes into extensive detail on model families, knobs, and response fields. While every sentence is informative, it could be more concise or better structured.

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

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

Given the complexity (9 parameters, no output schema), the description is remarkably complete. It covers purpose, model families, response structure, parameter interactions, caching, and diagnostics for empty segments, fully compensating for the missing 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 schema already documents all 9 parameters. The main description provides contextual insights on parameter usage (e.g., min_kelly, slippage_pp) but does not significantly enrich individual parameter semantics beyond what the schema provides.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also contextualizes the use case ('what should I bet on today') and distinguishes it from generic market scanning, though it doesn't explicitly differentiate from sibling tools.

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

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

The description provides clear context for when to use the tool (discovering opportunities without paging hundreds of markets) and details filtering knobs. However, it does not explicitly mention when not to use it or compare with sibling tools like polymarket_arbitrage.

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 reveals significant behavioral details beyond the annotations (readOnlyHint, idempotentHint, etc.). It explains the snapshot TTL (60 days), computation of decay from daily closes (not intraday), and the meaning of expired items. 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 with labeled sections (ARGs, RESPONSE, LIMITS). Every sentence contributes to understanding. It is longer than minimal but earns its length due to the complexity of the output structure.

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

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

The tool has no output schema, so the description fully explains the return value structure (tracked, expired, snapshot_dates) and computed fields (trend, decay_pp_per_day). Limits and parameter behavior are covered. This is comprehensive for a 2-param tool with optional parameters.

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 describes both parameters with 100% coverage. The description adds contextual details (default 14 for days, clamp 2-30, default '1wk' for window) that aid understanding, but the schema covers the core semantics. Overall, the description adds moderate value.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific question about how long an edge has existed and if it is shrinking. The verb 'track' matches the name, and it distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence rather than current edges.

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

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

The description implies when to use the tool (e.g., comparing a fresh wide edge to an old one) and provides default parameter values. It does not explicitly state when not to use it or list alternatives, but the example scenario and response structure give clear context for appropriate usage.

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

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

The description details returned fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.) for both modes. It does not contradict annotations (readOnlyHint: true matches checking behavior) and adds value beyond annotations by explaining the tool's analytical outputs and risks.

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 fairly long but well-structured with sections (REQUIRES, SINGLE-MARKET, BASKET) and front-loaded with the core purpose. It avoids unnecessary repetition and each sentence adds value, though it could be slightly more terse.

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

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

No output schema exists, so the description must explain return values, which it does thoroughly for both modes. It also covers pitfalls (partial fills, unhedged risk) and provides numbers context. This is complete for a check 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%, baseline 3. The description adds context like side default auto in basket mode and size_usd interpreted as settlement notional in basket, and the requirement for one of market or event. This provides meaning beyond the schema.

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

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

The description clearly states the tool checks realizable-vs-theoretical edge against live CLOB order-book depth, with distinct single-market and basket modes. The verb 'check' and resource 'Polymarket fill risk' are specific, and it differentiates from siblings like polymarket_arbitrage and polymarket_edges by its focus on fill risk.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It warns about partial basket fills converting arb into unhedged directional positions, providing clear when-to-use and alternatives.

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

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

The description adds significant behavioral context beyond annotations: edge cases like skipped cross types, temporal alignment checks, and compatibility scenarios. However, it does not mention potential rate limits or authentication needs, which are minor omissions given annotations already indicate safe read-only 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 fairly long but well-structured: purpose first, then modes, response, safety fields. Every sentence adds necessary information, though a slight trim could improve conciseness without losing context.

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

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

Despite no output schema, the description thoroughly explains the response structure including leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, and skipped cross counters. It covers all important edge cases for a cross-venue spread tool.

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

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

Schema coverage is 100%, and the description enriches parameter meaning by explaining the topic shortcuts list, the override behavior for explicit tickers, and the relationship between parameters in the two modes. This adds substantial value beyond schema descriptions.

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

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

The description clearly states the tool calculates cross-venue spread between Kalshi and Polymarket for the same resolving question, with two modes (topic shortcuts and explicit pairings). It distinguishes itself from siblings like polymarket_arbitrage 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 guidance on when to use each mode, explains the compatibility_warning in detail, warns that most pre-mapped topics return warnings, and clarifies temporal alignment requirements. This helps the agent decide when to use this tool over 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=true and idempotentHint=true. The description adds valuable context: the dual behavior (retrieve vs list), scoping to user identifier, and pairing with remember/forget. 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 extremely concise yet packed with essential information: purpose, usage, pairing, scoping. Every sentence adds value, with the main action front-loaded.

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

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

Despite no output schema, the description implicitly covers return types (value or list of keys). It could be more explicit about error handling or format, but overall it is sufficiently complete for a simple retrieval 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?

The input schema covers the single parameter with a clear description. The description does not add new parameter details beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves a saved value or lists all saved keys, with explicit mention of the related tools (remember, forget) and the resource (previously saved memories). It distinguishes itself from siblings by naming them.

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

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

The description explains when to use the tool (to look up previously stored context without re-deriving) and provides context about scoping. However, it does not explicitly state when not to use it or mention alternatives beyond the paired tools.

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

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

Discloses that mark_read modifies state (flags events as read) and that the tool is read-only and idempotent, consistent with annotations. Adds details about return fields and alternative access, enhancing understanding 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?

Concise yet information-dense. Each of the three sentences adds value: first describes core function, second adds filter details, third addresses state management and alternatives. No waste.

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

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

Given no output schema, the description explains return fields (source, citation_uri, payload) and behavior of mark_read and unread_only. All 5 parameters are covered, and the tool's usage context is fully described.

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

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

All 5 parameters have schema descriptions (100% coverage), and the description enriches each: explains type is subscription type, since is ISO timestamp, mark_read and unread_only behavior, and limit range.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifying the return fields (source, citation_uri, payload). It distinguishes from siblings like 'list_subscriptions' by focusing on persisted feed alerts.

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

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

Provides explicit guidance on filtering by type and ISO timestamp, using mark_read to manage read state, and notes polling is fine. Offers an alternative endpoint for scripts/dashboards, clarifying 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral details: multi-source fan-out, GDELT→GNews fallback, USPTO deprecation soft-fail, and output format with citation URIs. 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 well-structured with example queries upfront and technical details following. It is informative but slightly verbose; a few sentences could be trimmed without losing clarity.

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

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

Given the absence of an output schema, the description sufficiently explains the return structure (changes grouped by source, total_changes, citation URIs). For a tool with moderate complexity and rich annotations, this is adequate but not exhaustive (e.g., no details on error states).

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 practical guidance: 'since' accepts ISO or relative shorthand with examples, 'type' is only 'company', 'value' can be ticker or CIK. It also recommends '30d' or '1m' for monitoring, which helps AI agents choose appropriate values.

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, listing sources (SEC EDGAR, GDELT/GNews, USPTO) and contrasting with entity_profile. The verb 'fan out' and examples like 'What's new with X' make the purpose immediately apparent.

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

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

The description explicitly states when to use this tool vs entity_profile, and provides multiple query examples. It also explains fallback behavior for GDELT→GNews and USPTO soft-failure, giving clear guidance on when results may be incomplete.

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 (idempotentHint=true, destructiveHint=false), the description adds key behavioral details: key-value pair scoped by identifier, persistent memory for authenticated users, 24-hour retention for anonymous sessions. This fully discloses important traits.

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 (about 60 words) and well-structured, starting with the core action, followed by usage guidance, then technical details. Every sentence adds value without redundancy.

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

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

Given the simple key-value write operation, the schema fully documents parameters, annotations provide safety hints, and the description covers scope, persistence, and sibling tools. No gaps remain for effective use.

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

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

Schema coverage is 100% with clear descriptions of key and value. The description adds minor context about scoping and examples but does not significantly enhance parameter meaning beyond the schema.

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

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

The description clearly states the tool saves data for reuse across conversations or sessions, with specific examples like resolved tickers and user preferences. It distinguishes from sibling tools 'recall' and 'forget' by naming them directly.

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

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

It explicitly advises when to use the tool ('when you discover something worth carrying forward') and provides alternatives: 'Pair with recall to retrieve later, forget to delete.' This gives clear usage 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 non-destructive. The description adds transparency about internal behavior: "Each call cascades through several lookup endpoints internally" and that it replaces 2-3 manual lookups. This informs the agent about potential latency and complexity beyond the annotations. No contradiction.

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

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

The description is a dense single paragraph but well-organized. It starts with engaging examples, then states the purpose, then details supported types. Every sentence adds value. Minor improvement could be using bullet points for the two types, but the current structure is clear and not overly verbose.

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

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

Given the tool's complexity (two entity types, multiple output fields, no output schema), the description is quite complete. It specifies the canonical identifiers returned for each type, including citation URIs. It does not cover error cases (e.g., invalid input), but the open-world annotation partially covers that. Overall, an agent can use this description correctly.

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

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

Schema coverage is 100%, so baseline 3. The description adds significant value beyond the schema: it explains what each type returns (ticker, CIK, company_name for company; RxCUI, ingredient, brand for drug) and provides example inputs. This extra context helps the agent understand the outputs and use the tool effectively.

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

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

The description starts with concrete example queries that immediately clarify the tool's purpose: resolving names to official identifiers. It explicitly states it returns ticker/CIK for companies and RxCUI for drugs, and distinguishes itself from sibling tools by noting it replaces multiple manual lookups and should be used first when an ID is needed.

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

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

The description provides clear guidance: "Use FIRST whenever you have a name but need an ID." It also describes the input formats for each type (ticker, CIK, name for companies; brand/generic for drugs). While it does not explicitly list when NOT to use it or mention alternatives like entity_profile, the direct advice is sufficient for correct usage.

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

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

The description adds behavioral context beyond annotations: it probes each entity with ai_visibility_check, ranks results, and returns a ranked list with score, confidence, and signal density. Annotations already declare readOnlyHint, idempotentHint, destructiveHint. No contradiction.

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

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

Three succinct sentences. The purpose is front-loaded immediately. Every sentence adds essential information: what it does, how it works, and when to use. Zero 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 explains the return value (ranked list with score, confidence, signal density). It covers purpose, usage, parameters, behavior, and output. Given the complexity (4 params, composite tool), the description 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?

Schema coverage is 100%. The description adds value by clarifying that the first entity is treated as 'subject' for narrative and rest as competitors, and by giving a usage example for context. It also adds constraints (2-8 entities) not in 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 specifies the tool's purpose clearly: 'Compare AI visibility across multiple entities side-by-side.' It mentions probing each entity with ai_visibility_check and ranking by score. This distinguishes it from siblings like ai_visibility_check (single entity) and compare_entities (general 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?

The description explicitly says 'Useful for competitive AI-marketing audits' and gives an example query. It implies the tool is for side-by-side comparison, guiding when to use it. However, it does not explicitly state when not to use (e.g., for a single entity, use ai_visibility_check), which would improve clarity.

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, open-world. Description adds latency detail (5-30s for bundlephobia first measurement), partial failure handling, and return structure. 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?

Information dense and front-loaded, but lacks structured formatting like bullet points. Still concise and efficient.

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

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

Comprehensive: describes return fields, partial failure, latency, ecosystem scope, and alternatives. No output schema needed given rich 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?

Schema coverage is 100%, description adds context about scoped packages and default version behavior. Adds marginal value beyond schema.

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

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

Clearly states it's a composite check for npm packages using deps.dev and bundlephobia, evaluating safety, popularity, and size. Distinguishes from siblings by specifying NPM ecosystem and unique 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 says use when agent asks about npm package safety/popularity/size, and notes NPM-only with fallback for other ecosystems. Provides clear when-to-use and exclusions.

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

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

Annotations (readOnlyHint=true, idempotentHint=true) already indicate safety and idempotency. The description adds crucial behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K char cap with truncation and flagging, and output includes offsets and scores. 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 concise (3 sentences) but information-dense. It front-loads the core purpose, then usage guidance, then technical details. Each sentence serves a purpose, though some technical details could be more succinct.

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

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

For a tool with 3 parameters and no output schema, the description fully covers important aspects: semantics of each parameter, limitations (200K char cap, truncation flagging), output structure (passages with offsets and scores), and relationship to a sibling tool. It leaves 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?

Input schema covers all parameters (100% coverage). The description adds value by clarifying the 'text' parameter's max length (~200K chars), giving natural-language examples for 'query', and mentioning the default and range for 'limit'. It also explains the output format (offsets, scores) despite no output schema.

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

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

The description clearly states the tool's function: semantic search inside a fetched record. It specifies the use case (record too large for prompt), the output (top-N passages with character offsets and similarity scores), and differentiates from siblings by mentioning its pairing with ask_pipeworx_grounded.

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

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

The description explicitly says when to use ('record is too big to cram into the prompt'), provides practical query examples, and names a complementary sibling tool (ask_pipeworx_grounded) for grounding. It implies when not to use (if the record fits in the prompt).

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

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

Annotations already mark readOnlyHint=false and idempotentHint=true. The description adds important behavioral details: OAuth requirement, type-specific parameters, delivery constraints (SMS cap, phone verification), webhook signing and auto-disable. However, the hint of idempotency is not reflected in the description's wording ('creates', 'returns new subscription id'), which could be ambiguous.

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

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

The description is compact for its complexity, front-loading the core purpose. Each sentence adds value, though the delivery section is slightly dense. 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?

With no output schema, the description discloses the return value (new subscription id). It covers prerequisites (OAuth, phone verification), all subscription types with examples, and delivery channel nuances (including webhook failure handling). Comprehensive for a create tool.

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

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

Schema coverage is 100%, but the description goes far beyond enum names by providing real-world examples (e.g., items:['5.02'] for sec_8k, topic:'fed' for polymarket_edge) and detailed delivery options (SMS cap, webhook HMAC signing). This adds significant value for an agent.

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

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

The description clearly states the verb ('Create'), the resource ('proactive monitoring subscription to a live-data event stream'), and provides concrete examples of supported types and delivery channels. It implicitly distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description gives clear context on when to use this tool (to subscribe to alerts) and details per type. However, it does not explicitly exclude alternatives (e.g., when to use list_subscriptions instead), though the purpose is clear enough.

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

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

The description aligns with annotations (read-only, idempotent) and adds behavioral context: it is a non-destructive, informational tool that returns example questions with tool shapes.

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 verbose with a list of categories and some redundancy (e.g., repeating 'what is Pipeworx good for?'), but it is well-structured with front-loaded purpose.

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

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

Despite no output schema, the description fully explains what the tool returns (category-bucketed questions with tool shapes) and when to use it, sufficient for its simple functionality.

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 enhances the schema by providing concrete examples for the topic parameter (e.g., 'finance', 'pharma'), adding significant value.

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

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

The description clearly states the tool is an onboarding entry point that returns category-bucketed example questions, specifying verb+resource and distinguishing from siblings like ask_pipeworx.

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

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

It explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you,' providing clear context, but does not explicitly mention alternatives or when not to use it.

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

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

Beyond annotations (which indicate non-readonly, non-destructive, idempotent), description adds ownership enforcement, deactivation behavior, and preservation of historical events via recent_alerts. No contradictions.

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

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

Three concise sentences each adding unique value: purpose, ownership, and side effects. 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?

Explains return effect (deactivation) and links to sibling tool recent_alerts. Missing error handling for invalid ids, but adequate for a simple tool with one parameter and annotations.

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

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

Schema covers parameter fully with description 'Subscription id (uuid) returned by subscribe.' Description adds no additional parameter semantics beyond schema; baseline 3.

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

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

Description clearly states verb 'Cancel' and resource 'subscription by id'. It distinguishes from sibling subscribe by indicating it's the inverse operation.

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

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

Implies usage through ownership enforcement ('you can only cancel your own subscriptions'), but does not explicitly state when to use vs alternatives like list_subscriptions or subscribe.

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, and non-destructive hints. The description adds behavioral context by explaining the two verification pipelines (structured vs. grounded), the return format (verdict, value, citation, reasoning), and the fact that it 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?

The description is dense but front-loaded with keywords. Every sentence adds useful information, though it could be slightly more concise. Overall, it earns its length.

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

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

Despite lacking an output schema, the description thoroughly explains the return values (verdict types, actual value with citation, reasoning) and the fallback mechanism. It provides complete information for an AI agent to understand the tool's capabilities and outputs.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining how tolerance_pct works (overrides implied wording, capped at 5) and provides examples for the claim parameter. This improves 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 uses multiple synonyms for fact-checking and clearly states the tool's purpose: natural-language claim verification. It also distinguishes the tool from siblings by specifying the behavior for company-financial vs. other claims, making its scope well-defined.

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

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

The description explicitly states when to use the tool ('whenever the agent needs to check whether something a user said is factually correct') and provides context on the internal routing for different claim types. It does not explicitly exclude alternatives, but the guidance is clear enough for an AI agent.

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