Barcelona Events

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the tool is safe and idempotent. The description adds behavioral context: default free model, optional Anthropic probing with BYO key, and return structure (per-model and combined view). 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 a single paragraph of ~60 words, concise and front-loaded with the core action. It includes return format and usage scenarios without fluff. Slightly verbose in listing examples, 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 no output schema, the description sufficiently explains the return objects (score, confidence, signals, raw_response per model plus combined view). It covers key behavior (free vs paid model, key passthrough). An agent can understand inputs and outputs. Missing details on scoring algorithm are acceptable for a probing 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. The description adds value beyond schema: explains default model is free (Workers AI Llama-3.3-70b), that _apiKey is passed directly to Anthropic, and that 'context' disambiguates. This extra context raises the score to 4.

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

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

The description clearly states the tool's purpose: probe LLMs for knowledge about an entity and score visibility (0-100) per model. It specifies the verb 'probe', the resource (LLMs), and the output (score per model). It distinguishes from sibling tools by focusing on AI visibility scoring, unlike 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 mentions use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not directly state when not to use or name alternatives, but the context is clear enough for an agent to decide. Could improve by mentioning exclusions or specific sibling 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?

Adds behavioral context beyond annotations: routes to 4,552 tools, returns structured answer with pipeworx:// citation URIs, works on all tiers, and handles news/breaking-news. Annotations already declare safety and idempotency; description enhances 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?

Front-loaded with key directive, but includes lengthy lists of domains and examples that could be trimmed. Still structured effectively with clear sections.

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 purpose, usage, alternatives, and examples. No output schema is provided, so the description's mention of 'structured answer with citations' suffices. Could mention error handling but not critical for a query 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% (all parameters documented). The description does not add meaning beyond the schema; it simply states the question parameter is natural language. 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: 'PREFER OVER WEB SEARCH for questions about current or historical data' and lists specific domains (SEC filings, FDA drugs, etc.). It distinguishes from siblings by explicitly naming alternatives like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and step-up conditions for ask_pipeworx_grounded and deep_research. Also outlines query intent trigger words ('what is', 'look up', etc.).

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. The description adds detailed return structure: '{answer, evidence (verbatim quote), confidence, source, fetched_at, refusal_reason:null}' and explicit refusal reasons. It also notes the extra LLM call cost. No contradiction with annotations.

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

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

Concise yet comprehensive: two sentences for purpose, one for return structure, one for usage guidance. Information is front-loaded and each sentence adds 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?

Despite no output schema, the description fully covers the return format for both success and failure cases. It explains when to use vs. sibling, mentions the cost, and provides refusal categories. For a complex, high-stakes tool, this is fully 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% with all 6 parameters described (including aliases). The description adds minimal parameter semantics beyond what the schema provides; it recontextualizes that the question is used for routing and extraction, but the schema already states 'Your question in natural language.' Baseline of 3 is appropriate.

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

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

The description starts with 'Hallucination-resistant answer mode for high-stakes reads' and clearly distinguishes from ask_pipeworx by explaining the extraction step: 'EXTRACTS the answer using ONLY what the tool result contains.' It specifies the verb (answer/extract) and resource (tool results), and differentiates from its sibling ask_pipeworx.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' Also advises against casual use: 'prefer ask_pipeworx for casual lookups.' The cost trade-off ('Costs one extra LLM call') is noted.

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 fully discloses behavioral traits beyond annotations: it explains fan-out logic, match confidence handling, parent event extraction, news field fallbacks, safety short-circuits, and resolution rule risks. It contradicts no annotations (readOnlyHint, idempotentHint, destructiveHint) and adds substantial 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 excessively long and unstructured, reading as a dense manual. While front-loaded with purpose, it buries many details in prose. A more concise, bulleted structure would improve readability for an AI agent.

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 remarkably complete. It covers all relevant aspects: match confidence, parent events, news error handling, safety, spread, closed markets, and resolution rules. No gaps identified.

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 three parameters described). The description adds little beyond schema, mainly reiterating parameter purposes. Baseline 3 is appropriate as schema already defines parameters, and the description provides no significant new semantics.

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: researching Polymarket bets by pulling Pipeworx data. It specifies input types (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison). It also explicitly states use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z', distinguishing it 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?

The description provides extensive usage context, including when to use (bet research), specific classifiers, fan-out examples, and safety checks. It does not explicitly state when not to use, but sibling tool names imply alternatives. The guidance is detailed and helpful, though a clear exclusion statement would improve it.

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

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

Annotations indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds significant context: data sources (SEC EDGAR/XBRL for company financials, FAERS for drugs), correct handling of off-calendar fiscal years, sorting by primary metric, and return format with citation URIs. No contradictions with annotations.

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

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

The description is well-structured with separate parts for company and drug behavior, and includes example queries. It is slightly lengthy but every sentence adds value. Front-loading could be improved, but it remains informative without verbosity.

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 the return includes paired data and citation URIs, and mentions sorting. It covers the essential behavior for a comparison tool. It could explicitly state the response structure, but the provided information is sufficient for an agent to understand what to expect.

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

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

Input schema covers both parameters with 100% description coverage. The description adds meaning by explaining what each entity type returns (e.g., company pulls specific financial metrics, drug pulls adverse event counts) and provides examples of valid values (tickers/CIKs, drug names). This goes beyond the schema's basic descriptions.

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

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

The description clearly states that the tool performs side-by-side comparisons of 2-5 companies or drugs in a single call, specifying data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/clinical trials for drugs). It distinguishes from sequential single-pack lookups and gives example queries, making the purpose highly specific and 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 explicitly lists when to use this tool with example phrases like 'Compare X and Y' and 'rank these companies,' and instructs to prefer it over sequential lookups. It does not explicitly state when not to use it, but the sibling tools include entity_profile for single lookups, which is 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context beyond annotations, such as account requirements (free/paid tiers), time expectation (15-60s), the parallel decomposition process, return format (findings packet with verbatim evidence, confidence, source, gaps[]), and the fact that it is not open-web search. 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-structured and front-loaded with critical information (account requirement, alternatives, core functionality). Every sentence adds value, though some details (like the exact numbers 1160 and 4,552) could be considered extraneous. However, they contribute to clarity and specificity.

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 (multi-step research, parallel tool routing, 2 parameters, no output schema), the description covers all necessary aspects: purpose, prerequisites, behavior, return format, limitations, and time expectations. It provides a complete mental model for an AI agent to decide when and how to invoke 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% with descriptions for both parameters. The description adds further nuance to the 'depth' parameter (quick=3, standard=5, thorough=8) and explains that 'question' can be broad/multi-part as decomposition is the point. This enriches the schema descriptions and helps the agent 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 states that deep_research performs grounded multi-source research across 1160 structured data sources, decomposing questions into facets and using 4,552 tools in parallel. It explicitly distinguishes from siblings like ask_pipeworx by stating that deep_research is for broad/multi-part questions over structured data, not open-web search.

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 deep_research (broad/multi-part questions over structured data like 'compare X and Y's regulatory + financial exposure') and when not to use it (breaking news, colloquial current news, single lookups). It recommends ask_pipeworx for single lookups and asks users to prefer ask_pipeworx for current news topics, giving clear alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by explaining the return format (top-N most relevant tools with schemas and examples) and stating results are ready to call without a second lookup. 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 relatively concise given the amount of information. The list of domains is a bit long but provides concrete examples. It is front-loaded with the verb and resource. Each 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?

No output schema exists, but the description adequately explains what is returned (top-N tools with names, descriptions, schemas, examples). Given the tool's simplicity (searching a catalog of tools) and rich annotations, 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%, but the description adds value by listing aliases for the query parameter, giving style examples, and emphasizing natural language input. This goes beyond the schema descriptions which simply define aliases.

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 'discover' and names the resource 'tools'. It lists many example domains, clearly distinguishing this from sibling tools like search_within or deep_research by positioning it as a first-step tool to see available options.

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 needing to browse/search/discover tools for listed domains. Advises calling it first when many tools are available. Does not explicitly state when not to use, but the context is clear. Could be slightly improved with direct exclusion examples.

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

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

Beyond annotations (readOnly, idempotent), the description discloses implementation details: fan-out across multiple sources, soft-fail for patents due to API sunset, fallback for news (GDELT to GNews), and output structure (fields, sorting).

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-structured: starts with usage examples, then purpose, output details, and limitations. It is front-loaded and organized, though slightly verbose.

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

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

Given no output schema and high complexity, the description thoroughly explains all return fields (CIK, filings with URIs, fundamentals sorted, patents with sunset, news fallback, LEI). It leaves no critical gaps for an agent.

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

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

Schema coverage is 100% and already describes parameters (type, value) sufficiently. The description adds examples but no new semantic constraints or behaviors 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: generating a full cross-source profile of a US public company. It distinguishes from sibling tools by emphasizing preference over chaining individual lookups and referencing resolve_entity for name resolution.

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

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

Provides explicit when-to-use guidance (when user asks for a holistic view) and when-not-to-use (if only a name, use resolve_entity). It also gives an explicit preference rule: always prefer over single-pack 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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by stating that content is in Catalan/Spanish, which is behavioral context beyond annotations. 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 sentences long, with each sentence adding essential information: purpose, filters, and content language. No redundant or unnecessary words; it is efficiently 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 that the tool has 6 parameters with full schema descriptions and no output schema, the description covers all essential aspects: what it does, filters available, examples, and language constraint. It mentions return fields (venue, district, coordinates, dates) implicitly through the overall purpose, making it complete for an AI agent.

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

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

Schema coverage is 100%, so parameters are well-documented. The description enriches the schema by providing concrete examples for keyword ('música', 'exposició', 'infantil') and district ('Eixample', 'Ciutat Vella', etc.), which helps an AI agent select 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 states the tool finds upcoming cultural events in Barcelona, Spain, with specific filters. The verb 'Find' and resource 'cultural events & activities' are precise, and the geographic scope (Barcelona, Spain) distinguishes it from other 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 mentions filter options (keyword, district, date window) and provides example values for district and keyword, helping the agent understand how to use it. However, it does not explicitly state when to use this tool over alternatives or when not to use it, but since siblings do not include other event tools, the implicit guidance 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 provide destructiveHint=true and idempotentHint=true. The description adds no new behavioral information such as permanence of deletion or side effects, beyond what annotations declare.

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

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

Two concise sentences with front-loaded key action; 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?

For a simple tool with one parameter and no output schema, the description gives usage context and pairs. However, it omits mention of irreversibility or any confirmation.

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 does not add any parameter details beyond what the schema already provides for '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 clearly states the verb 'Delete' and the resource 'previously stored memory by key', and distinguishes from siblings 'remember' and 'recall'.

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

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

Explicitly lists when to use ('context is stale, task is done, clear sensitive data') and suggests pairing with related tools, though no when-not-to-use is given.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive, so the behavioral safety is well-covered. The description adds context: it fetches the page, extracts title/description/key links, and outputs a text blob. It does not contradict annotations. However, it could disclose potential issues like rate limiting or handling of non-HTTP pages, so it scores a 3—adequate but not improved beyond annotations.

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

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

The description is concise: three sentences front-load the purpose, list key actions, and give concrete use cases. Every sentence adds value, with no redundant or vague language.

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 task (fetch and format) and rich annotations, the description is nearly complete. It explains the output (single text blob for site-root/llms.txt) and use cases. It lacks details on error handling or behavior for invalid URLs, but these are minor; the tool is straightforward enough for agent selection.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (url and max_links). The description does not add new meaning beyond what the schema provides—it merely restates 'URL' and mentions a default for max_links. Baseline is 3 for high coverage, and the description offers no extra 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 title and description clearly state the tool's purpose: generating a production-ready llms.txt file for any URL. It specifies the exact output format (standard llms.txt markdown) and the actions it performs (fetches, extracts, emits). This distinguishes it from sibling tools, none of which directly overlap.

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 usage examples ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), but does not explicitly state when not to use it or mention alternative tools (e.g., scan_competitor_ai_presence). The guidance is implied rather than explicit, so it meets a baseline but lacks exclusion criteria.

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. The description adds that it returns specific fields and lists only active subscriptions by default, which provides additional 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?

Two sentences: first states purpose and return fields, second gives usage guidance. No wasted words, information is front-loaded.

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

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

For a simple list tool with one optional boolean parameter and comprehensive annotations, the description fully covers what the tool does, what it returns, and when to use it. 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 for the single parameter (include_inactive) is 100%, so the description's main value is contextualizing the default behavior (active subscriptions) and linking it to usage. This adds modest 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 lists the caller's active subscriptions and specifies the exact fields returned (id, type, params, etc.). It distinguishes itself from sibling tools like subscribe/unsubscribe by being a read-only list 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?

Explicitly advises using the tool to review subscriptions before adding more or to find an ID to cancel. This provides clear when-to-use guidance, though it does not explicitly state when not to use it.

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

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

The description adds behavioral context beyond the annotations, such as rate limits, free usage, and quota exemption. Annotations (readOnlyHint: false, destructiveHint: false) are consistent with the description's implied write operation, so no contradiction exists.

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, with clear sections separated by periods. It front-loads the main purpose and then provides usage details, all without unnecessary words.

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

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

Given the tool's simplicity (no output schema, straightforward parameters), the description covers all necessary aspects: purpose, usage, limitations, and parameter tips. It is complete and leaves no gaps for an agent to misinterpret.

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 has 100% description coverage, but the description adds extra context for the 'context' parameter (optional, relates to pack, tool, vertical) and clarifies the enum values for 'type'. This adds value beyond the schema alone.

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

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

The description clearly states the tool's purpose: to send feedback to the Pipeworx team for bugs, features, data gaps, or praise. It uses a specific verb ('Tell') and resource ('Pipeworx team'), and it easily distinguishes itself from sibling tools, none of which are feedback-related.

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 (bug, feature, data_gap, praise) and what to avoid (e.g., don't paste end-user prompts). It also includes usage restrictions (rate-limited to 5 per identifier per day) and notes it does not count against quota.

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?

Adds value beyond annotations by disclosing that the data is self-aggregating from CF analytics-engine, contains no PII, and is cached 5min-1h depending on window. Annotations already declare readOnlyHint=true and idempotentHint=true, so 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 concise (three sentences plus bulleted list) and front-loaded with the core purpose. Every sentence adds value, 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 one optional parameter and no output schema, the description covers return content, caching behavior, and use cases completely. 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?

The only parameter (window) has 100% schema coverage, but the description adds meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose a 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 it returns top tools, top packs, and total call volume over recent windows, using a specific verb ('returns') and resource ('what other AI agents are calling on Pipeworx'). It distinguishes from sibling tools like discover_tools and ask_pipeworx by focusing on aggregate trending data.

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

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

Provides three explicit use cases (discovering hot data sources, confirming canonical tools, checking alignment) that guide when to use this tool. Does not explicitly state when not to use it or direct to siblings, but the use cases are clear and practical.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds extensive behavioral context: scanning process, Jaccard similarity filter, placeholder filter, fill check with book depth, and trade advisories. 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 lengthy and dense with technical details, which may hinder quick parsing. While well-structured with sections and examples, it could be more concise by front-loading key purpose and mode distinctions.

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

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

Despite no output schema, the description explains the response structure (opportunities array with fields, partition check info). It covers caveats like fill check, low similarity filtering, and realizable edge. Comprehensive for a complex arbitrage 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?

Both parameters have schema descriptions (100% coverage). The description adds meaning by explaining what each mode does with the parameter values, including examples and internal processing like partition checks and cross-event searches.

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 as finding arbitrage opportunities via monotonicity violations and partition-sum checks, and clearly distinguishes three modes (no args, event, topic) with specific use cases. It differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance is provided for each mode: no args for trending scan, event for specific markets, topic for cross-event scanning. It mentions when to use each and references sibling tools for custom sizing. However, it does not explicitly state when not to use the tool or exclude cases.

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 extensive behavioral context beyond annotations, including caching behavior (1h KV), detailed edge calculation logic, slippage assumptions, Kelly fractions, filter mechanisms, and diagnostics. Annotations already indicate idempotent/readOnly, so the description enriches the operational understanding.

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

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

The description is thorough but very lengthy, diving into technical model details and parameter interactions. While each sentence is substantive, the density reduces scanability. A more structured approach (e.g., bullets) could improve conciseness.

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 provides comprehensive context: response structure by segment, diagnostics, caching, and exclusion reasons. It compensates for missing output schema by detailing return fields.

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%, providing initial parameter meanings. The description adds value by explaining how parameters like min_edge_pp, slippage_pp, and min_liquidity fit into the overall edge evaluation algorithm, offering context not in the schema.

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

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

The description starts with a clear verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It immediately distinguishes the tool from siblings by stating its unique purpose of identifying edge opportunities using Pipeworx 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 states it is 'Built for what should I bet on today' and mentions tradeable-edge knobs, but it does not explicitly specify when to avoid using this tool or compare it to other Polymarket tools. Usage context is implied but not fully delineated.

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, openWorldHint, idempotentHint, non-destructive. The description adds significant behavioral context: history depth bounded by 60-day snapshot TTL, data from snapshot enabling, decay from daily closes (not intraday), and explanation of snapshot gaps. 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 fairly long but well-structured: starts with core question, then details response fields, then limits. Each sentence adds value without unnecessary verbosity. Minor improvement possible in tightening.

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 (time-series decay telemetry) and no output schema, the description explains the full response structure (tracked, expired, snapshot_dates) and key limits. Covers most agent needs but could include example output or clarify edge cases.

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

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

Schema coverage is 100% and description also documents default values and limits. Adds context for 'window' (snapshot family like 24hr, 1wk, 1mo) and explains that gaps = no scan that day. Slight redundancy but provides clarity beyond schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and implicitly distinguishes from siblings like polymarket_edges by focusing on time-series 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 implies usage through the example (a fresh wide edge vs. a 3-week-old wide edge) but does not explicitly state when to use this tool versus alternatives like polymarket_edges or polymarket_arbitrage. No direct exclusions are provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral details: 'walks the ladder', return fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.), and risks like forced_directional_risk. While it doesn't mention side effects or rate limits, the annotations cover safety.

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

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

The description is longer but well-structured with sections for REQUIREMENTS, SINGLE-MARKET, BASKET, and USE THIS. It is front-loaded with the core purpose. Every sentence adds value, though minor redundancy could be trimmed. For the complexity, it is 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 (two modes, 4 params, no output schema), the description covers return fields, usage scenarios, and risks. It explains what the tool returns and why it matters. With no output schema, the inclusion of return fields is critical. It is sufficiently complete for an AI agent to use 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%, baseline 3. The description adds operational semantics: explains mode-dependent usage (market slug vs event slug), size_usd interpretation for basket mode as 'settlement notional', and side defaults (auto for basket). 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 states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes between single-market and basket modes and explicitly ties its usage to siblings like polymarket_arbitrage and polymarket_edges, making the purpose specific and actionable.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains the reasoning, detailing why theoretical overround may not be capturable and how partial fills create unhedged positions.

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 (readOnly, idempotent, etc.), description adds rich behavioral detail: two modes, response structure including compatibility_warning cases, temporal_alignment, skipped_cross counters. Completely consistent with 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?

Description is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS), front-loaded with purpose and modes. Every sentence adds value, no fluff, appropriately sized 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 no output schema, description fully explains response fields (leg-by-leg prices, matched spreads, compatibility_warning, temporal_alignment, skipped_cross counters). Covers all edge cases and provides complete understanding of tool behavior.

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

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

Schema coverage is 100% but description adds meaning: explains topic macros, overriding behavior for explicit parameters, and how modes interact. Provides examples and clarifies that topic auto-fetches, enhancing understanding 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 it computes cross-venue spread between Kalshi and Polymarket for the same resolving question, and distinguishes from sibling tools like polymorphic_arbitrage by specifying the two venues. It provides clear verb+resource and multiple use-case scenarios.

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 two-mode usage (topic shortcuts or explicit IDs) with clear instructions when to use each. Detailed warnings about compatibility warnings and that pre-mapped topics may not be tradeable, offering explicit when-not and cautions.

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 scoping to identifier and behavior when key is omitted (list all keys), which is valuable beyond annotations. No contradictions.

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

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

Three sentences, front-loaded with action, no fluff. Efficient and to the point.

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 optional parameter, no output schema, and annotations covering safety, the description is fully adequate. Explains return behavior (list all vs single value) and scope.

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

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

Schema coverage is 100% and description mostly repeats the schema's parameter explanation. It adds emphasis on omitting key to list all, but does not significantly augment semantics.

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

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

Description clearly states the tool retrieves a value saved via remember or lists all keys. Distinguishes from siblings 'remember' and 'forget' by naming them, and specifies the resource type (memory key-value store).

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: to look up context stored earlier without re-deriving it. Mentions pairing with remember/forget and scoping to identifier. Lacks explicit when-not-to-use, but context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, providing safety context. The description adds value by explaining that mark_read:true flags events as read for subsequent calls, and details the return fields. 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?

Four sentences with no filler. Front-loaded with purpose, dense with valuable information, and efficiently structured.

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

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

For a read-only tool with no output schema, the description covers return fields, filtering, side effects, and alternative access. All 5 parameters are adequately described in both schema and description. Context 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%, but the description enhances understanding by giving examples ('sec_8k'), clarifying the effect of mark_read on future calls, and explaining the unread_only parameter implicitly. Adds moderate 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?

The description clearly states it pulls fired events from the subscription feed, specifying the resource and action. It distinguishes from sibling tools like 'events' by focusing on subscription feed alerts and mentioning the HTTP endpoint 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?

Provides guidance on polling usage and alternative HTTP access for scripts/dashboards. Mentions filtering options and mark_read side effect, but does not explicitly state when not to use this tool versus others.

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

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

Annotations already indicate readOnlyHint and idempotentHint. The description adds rich behavioral context: fans out to multiple sources, mentions API sunset, fallback logic, and response 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?

The single dense paragraph is front-loaded with example queries. Every sentence adds value, though structuring into sections could improve readability.

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

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

Given complexity (multiple sources, fallback, no output schema), the description covers return structure, parameter nuances, and limitations comprehensively.

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

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

Schema coverage is 100% (baseline 3). Description adds value by explaining type is limited to 'company', providing since examples with recommended values, and noting value accepts ticker or CIK.

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

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

The description clearly states the tool provides recent changes for a company (SEC filings, news, patents) in a given time window. It distinguishes from sibling tool entity_profile and provides example queries.

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

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

The description explicitly advises when to use entity_profile instead, explains fallback behavior, and gives parameter usage guidance. It lacks explicit when-not-to-use for other siblings but is clear overall.

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 idempotent and non-destructive behavior. The description adds persistence details (authenticated vs anonymous, 24-hour retention) and scoping by identifier. Does not fully explain behavior on key overwrite, but adequate.

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 concise and efficiently structured. It states purpose, usage context, storage details, and pairing instructions in just a few sentences with no unnecessary words.

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

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

Given no output schema and two well-documented parameters, the description is sufficiently complete. It covers what the tool does, when to use it, and key behavioral aspects (persistence, scoping). Minor gap: no mention of return value or confirmation, but acceptable.

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 both parameters have descriptions. The description adds context with examples like 'subject_property', 'target_ticker', providing meaning beyond the schema's generic 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: 'Save data the agent will need to reuse later.' It specifies the resource (key-value pair), the verb (save), and distinguishes from siblings like recall and forget.

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

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

Provides explicit guidance on when to use: 'Use when you discover something worth carrying forward...' and pairs with recall/forget. However, it lacks explicit information on when not to use, which would be helpful but is not critical.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral context: it reveals that each call internally cascades through several lookup endpoints, thereby replacing multiple manual steps. It also details the return structure for each entity type, including citation URIs, which goes 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 remarkably concise yet comprehensive—five sentences cover purpose, usage guidelines, supported types, parameter examples, and return details. It is front-loaded with user-facing examples that immediately convey the tool's utility. No sentence is wasted.

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 explicitly states what each entity type returns (ticker, CIK, company name, citation URI for company; RxCUI, ingredient, brand, citation for drug). It covers all important aspects: input requirements, entity types, return fields, and the internal multi-step nature. For a tool with moderate complexity and no output schema, this level of detail 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 input schema provides descriptions for both parameters, and the description enriches these with concrete examples (e.g., 'AAPL', '0000320193', 'ozempic') and clarifies the expected format for each entity type. This additional context makes the parameter semantics crystal clear and compensates for any terseness 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 begins with concrete examples of user queries ("What's the ticker for...") and explicitly states the core function: resolving a user-spoken NAME to the canonical/official identifier. It also lists the supported entity types (company, drug) and the specific identifiers returned for each, leaving no ambiguity about what the tool does and how it differs from siblings that might operate on IDs 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?

The description gives an explicit directive: 'Use FIRST whenever you have a name but need an ID.' This clearly distinguishes when to use this tool versus alternatives (e.g., tools that accept an ID as input). It further explains that using resolve_entity replaces 2-3 manual lookups, reinforcing its role as a preliminary step.

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 safe (readOnly, idempotent). Description adds that it probes each entity with ai_visibility_check and returns a ranked list with specific fields (score, confidence, signal density). No contradiction.

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

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

Three sentences: core purpose, mechanics, use case. Front-loaded and no extraneous information.

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

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

No output schema, but description explains return format (ranked list, score, confidence, signal density). Also notes internal composition. Adequately complete for a tool with rich annotations and clearly defined 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?

Schema has 100% coverage, but description adds meaning: first entity is 'subject', rest are 'competitors'. Also explains interaction between models and _apiKey. 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?

Uses specific verb 'Compare' and resource 'AI visibility across multiple entities'. Distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities. Title and description align clearly.

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

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

Explicitly states it's for competitive AI-marketing audits and provides an example question. Implies usage context but does not explicitly exclude or mention alternatives beyond the sibling list.

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

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

Annotations indicate safe read operation; description adds details on partial failures, timing (5-30s for bundlephobia), ecosystem limitation (npm only), and sources_failed field. Goes beyond annotations.

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

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

Well-structured, front-loaded with main purpose, then usage, then behavior and limitations. 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?

No output schema, but description details return shape (summary block with fields, advisories, links, alternatives) and explains partial failure. Very complete given tool complexity.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds context: scoped packages accepted, version defaults to latest, and notes optionality of version.

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

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

The description clearly states it is a composite check for adding an npm package, specifying the verb 'scan' and resources (deps.dev, bundlephobia). It distinguishes from other tools like 'bet_research' which operate on different domains.

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 an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also mentions exclusions (PyPI via deps.dev:version) and partial failure 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?

Annotations already declare safe, idempotent behavior. Description adds key traits: truncation at 200K chars, embedding model (BGE-base-en), cosine similarity over 500-char windows, character offsets and similarity scores in output. No contradictions.

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

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

Three sentences, front-loaded with purpose. No wasted words. Each sentence adds unique information: purpose, when-to-use, behavioral details.

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

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

With 100% schema coverage and comprehensive annotations, description still adds: truncation, embedding details, output format (offsets+similarity), and workflow pairing. Completes the picture.

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

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

Schema covers all parameters. Description adds context: examples for query, max chars for text, and default/range for limit. Baseline 3, value from real-world examples raises score.

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

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

Clearly states semantic search inside a fetched record, with specific verb 'search' and resource 'inside a fetched record'. Distinguishes from sibling 'ask_pipeworx_grounded' by explaining the workflow pairing.

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

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

Explicitly says when to use: when record is too big for prompt. Describes pairing with ask_pipeworx_grounded. Does not explicitly list when not to use, 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 indicate readOnlyHint=false (writes), idempotentHint=true (safe to retry), openWorldHint=true. The description adds behavioral details: requires OAuth account, per-type parameter examples, delivery channel specifics (phone verification, 10/day SMS cap, webhook signing and auto-disable after 10 failures). 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: first sentence states purpose, then lists requirements, supported types with examples, and delivery options. It is moderately detailed but not overly verbose. Every sentence adds value, though some details (like webhook HMAC) could be more concisely summarized.

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

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

Given the tool's complexity (multiple types, delivery channels, auth requirements, no output schema), the description covers essential aspects: how to create a subscription, what types exist, delivery options, and requirements. It omits details like whether subscription updates are possible (handled by other tools) and how to retrieve the subscription ID later (list_subscriptions sibling). Overall, it is sufficient for an agent to correctly invoke 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 has 100% coverage with descriptions for all 3 parameters. The description adds significant value: explains each enum type (sec_8k, polymarket_edge, etc.) with examples, details params structure for each type, and elaborates on delivery channels beyond the schema (e.g., phone verification, SMS cap, webhook signing). This enriches the schema's information.

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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This provides a specific verb (create), resource (subscription to live-data event stream), and return value. It distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts which manage or view subscriptions differently.

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

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

The description explicitly requires a Pipeworx OAuth account and states that anonymous and BYO accounts cannot persist subscriptions, indicating when not to use it. It lists supported types and delivery channels with examples. However, it does not directly compare to sibling tools like list_subscriptions or unsubscribe, though the context makes the purpose 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=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by explaining the return format (category-bucketed examples with exact tool+argument shapes) and that it draws from a live catalog. No contradictions.

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

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

The description is relatively long but every sentence adds value. It front-loads trigger phrases and clearly explains the return and parameter behavior. Could be slightly more concise but still 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?

Without an output schema, the description adequately covers the return format (category-bucketed example questions with exact tool+argument shape) and notes it's from the live catalog. It also explains usage context. Sufficiently 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 description coverage is 100%. The description goes beyond the schema by providing concrete example values for the 'topic' parameter (finance, pharma, etc.) and explaining behavior when omitted (full cross-category spread).

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

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

The description explicitly states it returns category-bucketed example questions with tool+argument shapes, and lists trigger phrases like 'What can I ask Pipeworx?'. It distinguishes itself from sibling tools like 'ask_pipeworx' by being an onboarding entry point.

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

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

The description provides explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also implies when not to use (when you already know what to ask) and lists alternatives like ask_pipeworx, entity_profile, etc.

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: ownership enforcement, row deactivation (not deletion), and historical event availability. Annotations already indicate non-read-only, non-destructive, idempotent, and open-world, and the description aligns with and enriches these hints.

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

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

The description is concise with two sentences, front-loads the action, and avoids unnecessary detail. Every sentence adds value.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, behavior, and usage constraints. It could mention idempotency explicitly, but the annotations and deactivation hint cover it. 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?

The input schema already describes the 'id' parameter fully ('Subscription id (uuid) returned by subscribe'). The description adds no new parameter semantics beyond 'by id', so a baseline of 3 is appropriate given 100% schema coverage.

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

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

The description clearly states the action ('Cancel a subscription by id') and specifies the resource ('subscription'). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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

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

The description provides explicit usage guidelines: ownership enforcement ('only cancel your own subscriptions') and what happens to the row ('deactivated, not deleted'). It implies when not to use (others' subscriptions) but does not explicitly mention alternatives.

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

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

Discloses return format (verdict, structured form, actual value with citation, percent delta) and notes the v1 limitation to company-financial claims. Annotations already indicate safety, so description adds valuable behavioral details.

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

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

Front-loaded with purpose and examples, but the description is moderately long. Every sentence adds value, but could be slightly more concise.

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

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

For a single-parameter tool with no output schema, the description completely covers purpose, usage, scope, return values, and limitations. Annotations further enrich safety 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%, so baseline is 3. The description's external context (examples, usage) adds minimal new info about the parameter beyond what 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 explicitly states it's for natural-language claim verification using authoritative sources, with specific examples and scope. It clearly distinguishes the tool's function from siblings through detailed use-case language.

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 clear usage instructions: 'Use whenever the agent needs to check whether something a user said is factually correct.' Also mentions it replaces multiple sequential calls, giving strong context for when to invoke.

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