Madrid Events

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it probes LLMs, the default model is free (Workers AI), passing _apiKey enables Anthropic (user pays Anthropic directly), and it returns per-model and combined results. This fully informs the agent about the tool's behavior and side effects.

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) and well-structured: first sentence states the core action and output, second sentence provides model details and key requirements, third sentence summarizes return structure and use cases. No unnecessary words, and it is front-loaded with the most critical 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?

Despite having no output schema, the description explicitly states the return format per model (score, confidence, signals, raw_response) plus a combined view. It covers all 4 parameters, explains use cases, and annotations provide safety guarantees. The description is complete for an agent to understand how to use the tool effectively.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema: it clarifies the default model (workers-ai is free), explains that _apiKey is only needed for Anthropic and passes through directly to api.anthropic.com, and describes how 'context' helps disambiguate common names. This extra semantic clarity justifies a score of 4.

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

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

The description clearly states the tool's purpose: probe LLMs for knowledge about a business/brand/product/topic and score visibility from 0-100 per model. It uses specific verbs ('Probe', 'score') and distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on visibility scoring across multiple LLMs.

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 usage context: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the optional _apiKey for Anthropic. However, it does not explicitly state when not to use this tool or compare it to alternatives like 'entity_profile' or 'bet_research'.

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

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

Annotations already cover readOnly, openWorld, idempotent, non-destructive traits. The description adds that it routes to 4,552 tools and returns structured answers with citation URIs, providing useful behavioral context beyond annotations.

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

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

The description is long but well-structured and front-loaded with the key preference. Every sentence provides relevant guidance, though a slight reduction 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 tool's high complexity (4,552 tools) and no output schema, the description thoroughly explains functionality, use cases, and alternatives. It provides sufficient context for an agent to understand when and how to invoke it.

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% description coverage for all parameters. The description explains that the question parameter accepts natural language and lists aliases, adding value by clarifying the flexibility of input.

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 for factual questions about current/historical data from structured sources, with specific domains like SEC filings, FDA drugs, etc. It distinguishes from siblings by naming ask_pipeworx_grounded and deep_research as alternatives.

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 'PREFER OVER WEB SEARCH' and provides detailed guidance on when to use this tool vs others, including when to step up to ask_pipeworx_grounded or deep_research. Examples illustrate appropriate use 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 significant behavioral context beyond the annotations, such as the hallucination-resistance, the routing process over 4,552 tools, the structured refusal response (e.g., 'not_in_source'), and the exact output format. 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 (~100 words) with no wasted words. It is front-loaded with the core behavior, followed by usage guidelines and trade-offs. 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?

Given the high complexity (routing, refusal handling, output structure) and the lack of an output schema, the description provides a thorough overview: the extraction process, response format (answer, evidence, confidence, source, refusal_reason), and refusal reasons. It covers key contextual details 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?

The input schema covers all parameters with descriptions (100% coverage), and the description does not add substantial new semantics beyond stating it accepts natural language questions. The description mentions the response structure but not parameter details, so baseline 3 is appropriate.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' and explains it 'extracts the answer using ONLY what the tool result contains'. It distinguishes itself from the sibling 'ask_pipeworx' by being grounded and returning evidence.

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 ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'). It also mentions the cost trade-off of one extra LLM call, providing clear guidance on tool selection.

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

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

The description extensively discloses behavioral traits beyond annotations, including low-confidence match short-circuiting, closed market handling, wide spread warnings, resolution-rule risk (cancellation_rule parsing), fan-out behavior by category, and response shapes with safety mechanisms. No contradictions with annotations (readOnlyHint, idempotentHint, etc.).

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

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

The description is long and detailed, which is necessary given the tool's complexity, but it could be more structured with paragraphs or bullet points. The first sentence is a clear summary, but subsequent sections are dense and could overwhelm agents.

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

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

Given the tool's complexity and lack of output schema, the description covers all essential aspects: input formats, classifier types, fan-out examples, response structure, resolver contract, parent event extraction, news fallback handling, safety behaviors, and resolution rule risk. It leaves no major gap for an agent to misuse 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 all parameters have descriptions. The description adds context beyond the schema, such as explaining that 'market' can be a slug, URL, or question text, and clarifying the 'depth' and 'include_raw' behaviors. It enriches understanding of parameter usage and defaults.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input types (slug, URL, question text) and distinguishes itself from sibling tools by focusing on comprehensive data fan-out for a single bet, unlike other Polymarket-specific tools like polymarket_arbitrage or 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 explicit usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also includes detailed examples and classifier categories, helping agents understand when to apply the tool. However, it does not explicitly exclude cases where alternative sibling tools might be more appropriate.

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 rich behavioral detail: pulls latest SEC EDGAR/XBRL data, handles off-calendar fiscal years, sorts by primary metric, returns paired data with citation URIs, and replaces 8–15 sequential lookups. 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?

Single dense paragraph that is informative and front-loads purpose. Could be more structured (e.g., bullet points) but not overly long. 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 tool with 2 parameters and no output schema, the description covers entity types, data sources, sorting, citations, and efficiency gain. It is complete enough for an agent to understand usage and 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% with both parameters described. The description adds context: enum values for type with data sources and specifics, values parameter explained with examples and constraints (2–5, tickers vs names). Adds meaning beyond the schema.

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

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

The description clearly states the tool does side-by-side comparisons of 2–5 companies or drugs in one parallel call. It provides specific verb phrases like 'compare', 'rank', 'head to head', and distinguishes from sequential lookups and sibling tools like entity_profile.

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

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

Explicitly advises to prefer over sequential single-pack lookups and gives example queries. Does not explicitly list when not to use, but the positive 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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), description adds major behavioral context: account required, expected latency 15-60s, returns findings packet with evidence+confidence+source+citation, never invents (gaps array), and the parallel decomposition process. 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 thorough but somewhat verbose, repeating points about not being open-web search. However, it is front-loaded with the most critical info (account requirement and alternative) and the structure is logical. Minor redundancy prevents a 5.

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, no output schema, and rich annotations, the description fully covers what an AI agent needs: the type of data sources, parallel execution, result format (findings packet with gaps), expected latency, and clear differentiation from siblings. No gaps in completeness.

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 value by explaining depth enum values (quick=3, standard=5, thorough=8) and that thorough requires paid plan, plus clarifies that question can be broad/multi-part. This exceeds what the schema alone provides.

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

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

Description clearly states it performs grounded multi-source research across 1160 structured data sources, specifically distinguishing itself from open-web search and sibling tools like ask_pipeworx. It uses specific verbs like 'decomposes' and 'routes' and identifies the resource as Pipeworx's structured 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?

Description explicitly tells when to use this tool (broad/multi-part questions over structured data) and when not to (single lookups use ask_pipeworx; breaking/current news prefer ask_pipeworx). It also notes account requirements and that 'thorough' depth needs a paid plan, providing 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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description reveals that results include 'full input schemas (with curated examples)' and that each result is 'ready to call directly, no second schema lookup needed.' This adds significant behavioral context about output quality and usability.

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 a clear first sentence defining the tool, followed by use cases and output details. Slightly verbose with the list of domains, but each item adds value. Not wasteful overall.

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

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

Given no output schema, the description fully compensates by detailing the return format (top-N tools with names, descriptions, and full schemas). The agent has complete understanding of what to expect and how to interpret results.

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

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

With 100% schema coverage, baseline is 3. The description adds value by explaining query aliases, providing examples, and explicitly stating default and maximum for 'limit' (default 20, max 50). This justifies a score above baseline.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides a comprehensive list of domains (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools as the main discovery gateway, making its role 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?

Explicit guidance is given: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent when to use this tool versus directly invoking other tools, fulfilling the dimension's 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, openWorldHint, idempotentHint. The description adds significant behavioral details: it fans out across multiple sources, returns specific fields, notes patents soft-fails after May 2025, and names not supported. 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 detailed but well-structured, starting with example queries, then stating preference, then listing sources and return fields, then caveats. While somewhat lengthy, every sentence adds value and is front-loaded with the most important 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 (multiple data sources), two parameters, and no output schema, the description is complete. It covers input constraints, sources, return fields, fallback behavior, and a known limitation (patents sunset). The high annotation coverage further supports completeness.

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 both parameters. The description adds value by clarifying that value can be ticker or zero-padded CIK, names not supported, and type is only 'company'. This provides context beyond the schema's enum and description.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call'. It provides concrete examples like 'Tell me about X' and specifies the output includes CIK, filings, fundamentals, patents, news, and LEI, effectively distinguishing it from sibling tools like resolve_entity.

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 chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. Also warns that names are not supported and advises to use resolve_entity first, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, etc. The description adds useful context: events are for the next ~100 days, and content is in Spanish. 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. Each sentence adds distinct value: scope, filters, return fields. No redundant 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?

For a list tool with 6 optional parameters and no output schema, the description covers purpose, scope, filters, return fields, and language. Annotations cover safety and idempotence. The tool feels fully specified.

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 parameter descriptions. The description only summarizes filters (keyword, free, date window) without adding new 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 'Find cultural events & activities in Madrid, Spain' with a specific time window. The verb 'Find' and resource 'events' are precise, and the scope (Madrid, ~100 days) distinguishes it from unrelated 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 this tool: for cultural events in Madrid. It doesn't explicitly exclude alternatives, but no similar event tools are among siblings, so 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 indicate destructiveHint=true and idempotentHint=true. The description confirms the destructive nature but adds no additional behavioral context beyond what annotations provide. No contradiction.

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

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

Two concise sentences that front-load the action and include usage guidance. Every word 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?

For a simple tool with one parameter and no output schema, the description is complete: it states purpose, usage context, and pairing with siblings. Annotations cover safety. 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 schema covers the single parameter 'key' with description 'Memory key to delete' (100% coverage). The tool description does not add extra meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Delete'), the resource ('previously stored memory'), and the method ('by key'). It distinguishes itself from sibling tools by explicitly mentioning '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?

The description provides explicit guidance on when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with related tools. Missing explicit when-not 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, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details like fetching the page, extracting title/description/key links, and emitting standard markdown. It could mention external requests or rate limits for higher score.

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

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

The description is two sentences plus a short list of use cases. It is front-loaded with the main purpose, no wasted words, and well-structured. Every sentence earns its place.

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

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

With 2 parameters, no output schema, and clear annotations, the description covers the tool's functionality, output format, and use cases adequately. It mentions the standard llms.txt format and where to place the output, making it contextually complete for a simple 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 the schema already documents both parameters. The description adds context by explaining that the tool fetches the page and extracts content, which helps understand the url parameter's purpose. However, it does not add significant detail beyond the schema, so a 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 generates a production-ready llms.txt file for any URL, specifying the exact resource and action. It distinguishes itself from sibling tools by being unique in functionality, as none of the siblings directly target llms.txt generation.

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

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

The description explicitly lists three practical use cases (client site indexing, personal project, competitor auditing), providing good guidance. However, it does not explicitly state when not to use the tool, which would elevate it to a 5.

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?

Description adds behavioral context beyond annotations: it explains the default scope (active subscriptions), the effect of the include_inactive parameter, and the specific return fields. Annotations already declare safety, but the description fills in operational details.

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

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

Two sentences tightly pack purpose, output format, and usage guidance. No unnecessary words, and the key 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 tool with one optional parameter and strong annotations, the description covers all aspects: what it 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 is 100% with a single described parameter. The description reinforces the default behavior (active only) and ties the parameter to the concept of including inactive subscriptions, enhancing understanding beyond the schema description.

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

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

The description clearly states the verb 'List' and resource 'subscriptions', specifies the returned fields (id, type, params, etc.), and differentiates from sibling tools like subscribe and unsubscribe by being the only listing tool.

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 context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It clearly indicates when to use, though it does not explicitly state when not to use.

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

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

Beyond the annotation set (which is minimal), the description discloses rate limits ('5 per identifier per day'), that it is free and doesn't count against tool-call quota, and how feedback is processed ('digests daily and signal directly affects roadmap'). This fully informs the agent of behavioral constraints.

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 tight and well-structured: it begins with the core purpose, then usage context, then behavioral notes. Every sentence adds value, and the total length is appropriate for the complexity. No fluff.

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

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

Given the tool has three parameters (one enum, one optional nested object), no output schema, and moderate complexity, the description covers all necessary information: feedback types, how to fill fields, constraints (rate limit, quota), and processing. Nothing critical is missing.

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 extra meaning by explaining each enum value in the 'type' parameter, recommending specificity in 'message', and clarifying that 'context' is optional but helpful. This exceeds the baseline without being redundant.

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 for sending feedback ('Tell the Pipeworx team something is broken, missing, or needs to exist') and specifies four feedback types: bug, feature, data_gap, praise. This strongly distinguishes it from sibling tools which are primarily data retrieval or analysis tools.

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

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

The description explicitly states when to use the tool: for bugs ('a tool returns wrong/stale data'), for missing features ('a tool you wish existed isn't in the catalog'), and for praise. It also warns against pasting end-user prompts, providing clear contextual guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: caching behavior (5min-1h), data source (CF analytics-engine), and that no PII is included. This goes beyond the annotations.

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

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

The description is 4 sentences with a clear front-loaded main statement. It uses a bulleted list for use cases. Every sentence adds value without redundancy. 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 tool's simplicity (one optional parameter, no output schema), the description is complete. It explains the return structure (top tools, top packs, total call volume) and caching. No gaps remain for an agent to understand 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 one parameter described in the schema. The description adds meaning by explaining the implication of window choices ('shorter windows surface what's hot right now; longer windows show steady-state demand').

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

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

The description uses specific verbs ('returns') and clearly states the resource ('top tools, top packs, total call volume over a recent window'). It distinguishes from sibling tools by focusing on trending data, which no other sibling explicitly covers.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming canonical tools, seeing alignment). It implies when to use but does not provide when-not-to-use or alternatives, which would raise the score to 5.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds rich behavioral context: explains the algorithms (monotonicity checks, partition-sum checks, Jaccard similarity threshold, partition filter), fill check against live CLOB depth, and conditions for actionable signals. 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 verbose but well-structured: it starts with the main purpose, then explains modes in order, and ends with response format and fill check details. Every sentence is informative, and the length is justified by the tool's complexity. Slight redundancy with schema descriptions 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 adequately covers the response structure (opportunities with fields, partition check details, fill check results). It also explains edge cases (placeholder filtering, low Jaccard similarity) and references related tools, making the definition self-contained 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 description coverage is 100% with basic explanations for both parameters. The description adds significant value by elaborating on parameter behavior, providing concrete examples (slugs, topics), and detailing the internal logic for each mode. It goes beyond the schema's terse 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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between two modes (event and topic) and differentiates from sibling tools like polymarket_fill_risk by explicitly referencing them for custom sizing.

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: call with no args for trending scan, pass event for specific market, pass topic for cross-event scan. It recommends event mode for specific markets and explains when cross-event mode is beneficial. It also warns against trading when fill check shows zero edge and redirects custom sizing to another 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 read-only, so no contradiction. Description adds extensive behavioral detail: caching (1h KV), edge calculation (after slippage), 24h-move warning, filter diagnostics, segment explanations. Goes well beyond annotations.

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

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

Thorough yet well-structured: front-loaded purpose, segments, knobs, response structure. Could tighten model family details slightly, but every sentence adds value. Efficient for its depth.

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, so description fully covers return structure (by_segment, fed_candidates, diagnostics) and caching. Complete guidance for an agent to understand and invoke the tool correctly given its 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%, but the description adds critical usage context for each parameter: e.g., min_partition_leg_kelly explains interplay with min_kelly, max_spread_pp suggests values, slippage_pp notes typical costs. Adds significant 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?

Clear verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' Distinguishes from siblings like polymarket_arbitrage by focusing on edge detection, not arbitrage. 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?

Explicitly built for 'what should I bet on today,' provides context for when to use each segment. Notes Fed bets are excluded from ranking due to unreliable signal. Lacks explicit when-not-to-use or alternatives, but strong 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 readOnly and idempotent. The description adds value by detailing that data comes from daily snapshots with a 60-day TTL, decay computed from daily closes not intraday, and that gaps occur when no scan happened. This provides useful behavioral context beyond annotations.

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

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

The description is front-loaded with the core purpose and question. It then systematically explains the response structure and limits. While verbose, every sentence adds information, and the structure is logical. Could be slightly more concise but effective.

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

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

With no output schema, the description completely explains the response structure (tracked, expired, snapshot_dates). It covers what the tool returns, its parameters, and its limitations (TTL, start time). Annotations provide behavioral safety. The tool is fully documented for an 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?

Both parameters have schema descriptions that already cover lookback, default, clamp for 'days' and family for 'window'. The description nearly repeats these, adding only a stated 'max 30' which slightly differs from schema's 'clamp 2-30'. No significant new semantic value added.

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, answering the specific question of how long an edge has existed and whether it is shrinking. It distinguishes itself from the sibling tool 'polymarket_edges' by being a historical telemetry view built from snapshots.

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

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

The description implies usage through its core question, but does not explicitly state when to use this tool versus alternatives like 'polymarket_edges'. It lacks explicit when-not-to-use guidance or named 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, etc. The description adds behavioral context: it walks the order-book ladder, calculates slippage, and returns a verdict. It also explains the risk of thin books and partial fills. This adds value beyond the annotations.

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

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

The description is quite long but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET). Each sentence adds necessary information. It could be slightly more terse, but the verbosity is justified by the complexity of the tool. 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 tool's complexity (two modes, risk of partial fills) and the lack of output schema, the description is remarkably complete. It covers all parameters, return values, usage context, and risks. An agent can confidently decide when and how to use this tool based on this description alone.

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, but the tool description adds significant context: it explains the dual meaning of side and size_usd in single vs basket mode, clarifies defaults, and gives interpretation (e.g., 'shares per leg; each share pays $1'). This goes well beyond the 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 explicitly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes between single-market and basket modes, and lists the return values (e.g., top_of_book, vwap_fill_price, verdict). This is a specific verb-resource pair with clear scope.

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

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

The description gives explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the risk of partial fills and unhedged positions, effectively telling the agent when to use this tool instead of 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, idempotentHint=true, etc. The description adds extensive behavioral context: two modes, raw probability outputs, matched spreads, safety fields (compatibility_warning, temporal_alignment), and skipped counters for non-equivalent legs. 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 relatively long but well-structured: front-loaded purpose, then modes, response, safety fields, and warning. Each sentence adds unique information. Slightly verbose but justified given complexity.

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

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

Despite no output schema, the description thoroughly covers response structure (leg-by-leg prices, matched spreads), safety fields, and edge cases (non-equivalent bet shapes, temporal mismatch). Provides complete context for an AI agent to invoke correctly.

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

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

Schema coverage is 100%, so the schema documents parameters. The description adds meaning by explaining the two modes and providing enumerations for topic values and examples for explicit tickers, going beyond the schema's basics.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket, specifying the verb (compute/display), resource (spread), and differentiates from siblings like polymarket_arbitrage. It indicates two modes (topic shortcuts and explicit tickers) and what the output represents.

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

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

Explicitly describes two usage modes with examples of allowed topic values. Warns that most pre-mapped topics return compatibility warnings, advising caution. Implicitly guides when not to use (when compatibility warning fires) and distinguishes from other tools.

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

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

Annotations already declare readOnlyHint and idempotentHint; description adds scoping details (by identifier) and pairing with related tools, adding 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 concise sentences, front-loaded with action, no wasted words. Every sentence earns its place.

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

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

For a simple tool with one optional parameter and no output schema, the description fully explains behavior, scoping, and related tools. 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?

Input schema covers 100% of parameters, including description of 'key'. Description restates the same info without adding new syntax or format details, so baseline of 3 is appropriate.

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

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

Clearly states the verb (retrieve/list) and resource (saved memory), distinguishes from siblings like remember and forget, and provides specific use case examples.

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

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

Explicitly says to use for looking up previously saved context and not re-deriving. Could be improved by stating when not to use (e.g., if retrieval fails) but otherwise 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 value beyond annotations by explaining the mark_read behavior (flags events as read so next call shows newer ones), the nature of the feed (persisted), and the existence of an alternative endpoint. It does not contradict any 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 with no wasted words. The main purpose is front-loaded, and each subsequent sentence adds critical context (return format, filtering, mark_read effect, alternative endpoint).

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

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

Given no output schema, the description adequately specifies return values (source, citation_uri, raw payload). It covers filtering, state management with mark_read, and the alternative endpoint. With full annotation support for safety (readOnlyHint, idempotentHint), the description is highly 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 examples (e.g., 'sec_8k' for type, ISO timestamp for since) and explains mark_read and unread_only implicitly, enhancing understanding beyond the 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 pulls fired events from a subscription feed, specifying the resource (alerts) and what is returned (source, citation_uri, raw payload). The verb 'pull' and the noun 'alerts' make the action distinct from sibling tools like 'events' which may refer to a different concept.

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 usage context: filtering by type and since, setting mark_read, and notes that polling works fine. It also offers an alternative REST endpoint for scripts/dashboards. However, it does not explicitly instruct when not to use this tool or compare it to siblings like 'list_subscriptions' or 'events'.

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, idempotent), the description details the fan-out to multiple sources, fallback behavior (GDELT to GNews on rate limiting), soft-fail for patents post-May 2025, and the output format (grouped changes, citations, count). 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 dense paragraph. While packed with useful information, it lacks structure (e.g., bullet points or sections) and is longer than necessary, making it less scannable 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?

For a complex tool with 3 required parameters, no output schema, and multi-source behavior, the description covers all essential aspects: input semantics (including examples), processing logic (fan-out, fallback, soft-fail), output structure, and direct comparison to a sibling tool. There are no missing pieces.

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

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

The schema already describes all parameters (100% coverage). The description adds value by explaining 'since' accepts ISO dates or relative shorthand, suggesting specific values like '30d', and clarifying 'value' accepts ticker or CIK. This enhances usability beyond the schema.

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

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

The description clearly defines the tool as a change feed for a company, listing specific data sources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly distinguishing it from the sibling tool 'entity_profile' for static profiles.

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 example query patterns, explains the window parameter, and includes a direct instruction to use 'entity_profile' instead for static profile needs, effectively guiding when to use this tool vs 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?

Goes beyond annotations by explaining key-value storage, scoping by identifier, persistence differences for authenticated vs. anonymous (24 hours). Annotations provide idempotentHint=true; description adds lifecycle 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?

Description is efficient and well-organized: purpose first, then usage, then technical details. Slightly long but 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 key-value store with two parameters and no output schema, the description fully covers purpose, usage, behavior, and lifecycle. 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 has 100% coverage with descriptions for both key and value. Description adds example key conventions but does not significantly extend schema meaning. Baseline 3 is appropriate.

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

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

Description clearly states the tool saves data for reuse across conversations and sessions, with specific examples like resolved ticker or user preference. Differentiates from sibling tools recall and forget.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward'. Mentions pairing with recall and forget, providing context. No explicit when-not, but overall guidance is clear.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups.' This provides insight into internal behavior 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 description is well-structured and front-loaded with examples. It is comprehensive without being verbose. Every sentence adds value, though it could be slightly more concise by omitting the citation URI details which are part of the output explanation.

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 2 parameters and no output schema, the description provides complete information: input types, output specifics for each entity type, internal cascading behavior, and usage guidance. It covers all necessary details for an agent to correctly select and 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?

While schema coverage is 100%, the description adds significant meaning beyond the schema. It explains that for company, it returns ticker, CIK, company_name, and a citation URI; for drug, it returns RxCUI, ingredient, brand, and citation. It also clarifies that company input auto-disambiguates and that drug accepts brand or generic names.

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

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

The description clearly states the tool's purpose: resolving a user-spoken name to a canonical/official identifier. It provides specific examples and explicitly says 'Use FIRST whenever you have a name but need an ID,' which distinguishes it from sibling tools like compare_entities or entity_profile.

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

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

The description gives strong usage guidance: 'Use FIRST whenever you have a name but need an ID.' It details supported types and what each returns, making it clear when to use it. It could be slightly more explicit about when not to use it, but the 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?

Discloses that it probes each entity with ai_visibility_check, ranks by score, and returns score, confidence, signal density. Annotations already indicate read-only, idempotent, non-destructive; description adds internal behavior and output structure.

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, followed by mechanism and use case. Every sentence adds value; no redundancy or filler.

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 explains return format (ranked list with score, confidence, signal density). Parameter semantics are fully covered. Tool complexity is moderate and description addresses all key aspects.

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 with descriptions (100%). Description adds value by explaining that first entity is treated as 'subject' for narrative, models default to workers-ai, and context disambiguates names. This goes 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 compares AI visibility across entities side-by-side, probing each with ai_visibility_check and ranking results. Distinguishes from sibling ai_visibility_check (single entity) and compare_entities (generic 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 specific use case: competitive AI-marketing audits with example question. Implies when to use (audit context) but does not explicitly state when not to use or list alternatives. Clear context makes it easy to decide.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds valuable behavioral context: bundlephobia's first measurement latency (5-30s), sources_failed list on timeout, and that partial failures still return partial results. 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?

Single paragraph of 4-5 sentences, front-loaded with main purpose. Every sentence adds value: purpose, usage guidance, return structure, ecosystem limits, error behavior. No fluff or repetition.

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

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

For a tool with 2 params and no output schema, the description is remarkably complete. Lists all return fields (summary block, per-advisory, links, alternative versions), covers error handling and latency. No gaps given the composite 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 description coverage is 100% with both parameters described. Description adds extra meaning: version defaults to latest when omitted, scoped packages (@types/node) accepted. Explains effect of parameters in the composite check, exceeding schema 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?

Clearly states it's a composite check for npm packages combining deps.dev and bundlephobia data. Specific verb 'scan' and resource 'dependency' with explicit use case 'should I add this npm package'. Distinguishes from siblings by being the only npm-focused scanning tool in a list of unrelated tools.

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

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

Explicitly tells when to use: 'whenever an agent asks is X safe / popular / small' or 'what does adding lodash cost me'. Also specifies limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', guiding alternatives. Mentions partial failures and graceful degradation.

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. Description adds substantial behavioral details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and output format (passages with offsets and scores). 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?

Single paragraph but well-structured: core purpose first, then behavioral details, then pairing suggestion, then technical specifics. Every sentence adds value. Slightly dense but still concise.

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

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

Given the tool's complexity (semantic search with embeddings, truncation, pairing), the description covers all essential aspects: use case, limitations, pairing, output features. No output schema exists, but the description explains return values sufficiently.

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: for 'text' gives example context (SEC 10-K body), for 'query' provides natural-language examples, and for 'limit' mentions default and range. Explains output format indirectly, adding 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 specifies the tool performs semantic search inside a fetched record, with specific verbs ('Search Within'), resource ('a Source'), and output details (top-N passages with offsets and scores). Distinguishes from sibling ask_pipeworx_grounded by explaining 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 states when to use: when the record is too large to fit in the prompt. Provides context on saving context and returning only relevant passages. Mentions pairing with ask_pipeworx_grounded. Lacks explicit 'when not to use' or alternative tools from the sibling list, but the guidance is still strong.

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 (which are mostly neutral). Discloses account requirement, delivery constraints, that webhook secret is returned once, and auto-disable behavior. No contradiction with annotations (readOnlyHint=false, idempotentHint=true, etc.).

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

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

Well-structured with clear sections (purpose, prerequisites, types, delivery). Information-dense but not verbose. Could be slightly more concise, but 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?

Comprehensive for a complex tool with multiple types and delivery channels. Explains type-specific parameters, delivery constraints, and return value (id). No output schema, but description suffices.

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, but the description adds significant meaning with examples (e.g., 'items:["5.02"] = officer change') and explains delivery object properties beyond the schema, like the webhook HMAC signing and auto-disable.

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: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It distinguishes from sibling tools (list_subscriptions, unsubscribe) by focusing on creation, with specific types and examples.

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 prerequisites ('Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions)'), delivery options with constraints (10/day SMS cap, webhook auto-disable), and type examples. It lacks explicit 'when not to use' but is still very helpful.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral context by explaining the tool returns example questions with exact tool and argument shapes, drawn from a live catalog. There is 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 relatively long but well-structured, starting with common user queries and then providing a clear functional description. Every sentence adds information, 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 simple tool with one optional parameter and no output schema, the description is highly complete. It covers purpose, usage timing, parameter guidance, and even relates to sibling meta-tools, leaving no gaps for the agent.

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

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

Schema coverage is 100% with a clear description for the optional topic parameter. The description adds value beyond schema by stating 'Call with no arguments for full spread' and explaining how to focus with a topic, which is not in the schema.

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

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

The description uses specific verbs and resources: 'Returns category-bucketed example questions' and identifies the exact purpose as the onboarding entry point for Pipeworx. It clearly distinguishes from sibling tools by positioning itself as the first tool to use when the agent doesn't know what Pipeworx can do.

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

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

The description explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also provides context for calling meta-tools. While no explicit exclusion of alternatives is given, the clear onboarding purpose effectively guides 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?

Beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description reveals important behavioral traits: ownership enforcement (only own subscriptions can be canceled) and that the row is deactivated rather than deleted, preserving historical data. This adds significant value beyond the structured fields.

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 consists of two concise, front-loaded sentences. Every word serves a purpose: first sentence states the action, second provides essential behavioral details (ownership, deactivation, history). No redundancy or fluff.

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

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

For a simple tool with one parameter and no output schema, the description covers all critical aspects: purpose, ownership constraint, effect (deactivation), and side effect (history preservation). No gaps remain given the tool's complexity and available 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?

The schema already covers the single parameter (id) with its description. The description adds context by stating 'by id' and implying the id comes from subscribe, slightly enhancing understanding. With 100% schema coverage, the baseline is 3, and the 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 cancels a subscription by ID, using a specific verb ('Cancel') and resource ('subscription'). It distinguishes from sibling tools like subscribe (create), list_subscriptions (view), and recent_alerts (history) by noting that deactivation keeps historical events available via recent_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?

The description implies when to use this tool (to cancel a subscription) and mentions that historical events remain viewable through recent_alerts, but does not explicitly state when not to use it or name alternatives for comparison. The context is clear but lacks explicit exclusions.

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

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

The description adds behavioral context beyond annotations: it returns verdict, structured form, actual value with citation, and percent delta. It also notes v1 supports specific claims via SEC EDGAR+XBRL. 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 somewhat long but well-structured with examples and explicit efficiency gains. Every sentence adds value, and it is front-loaded with query patterns. Not overly verbose for the content needed.

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

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

Given the single parameter and no output schema, the description provides sufficient completeness: it explains the tool's scope, output format, and efficiency. It could mention edge-case handling, but overall it is adequate.

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

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

With 100% schema coverage and a single parameter, the schema already describes 'claim' well. The description adds examples and context about what types of claims are accepted, which enhances the schema's meaning.

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

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

The description explicitly lists natural-language query patterns and states 'natural-language claim verification against authoritative sources', clearly indicating the tool's purpose. It also distinguishes from siblings by noting it replaces multiple sequential calls.

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

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

The description says 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the supported domain (company-financial claims). It does not explicitly state when not to use it, but the context is clear.

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