xkcd

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable context: default model is free, Anthropic probing requires BYO API key, and returns per-model data (score, confidence, signals, raw_response). 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 a single, focused paragraph of four sentences. It front-loads the main purpose, then explains options and returns. Every sentence earns its place; no wasted words.

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

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

Despite no output schema, the description details the return structure (per-model object + combined view) and covers parameters and use cases. Given the tool's moderate complexity, it provides sufficient context for agent invocation.

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

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

All four parameters have descriptions in the schema (100% coverage). The description enhances understanding by explaining the default model, when _apiKey is needed, and the purpose of the context parameter. Adds meaning beyond schema.

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

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

The description clearly states the tool's purpose: to probe LLMs for knowledge about an entity and score visibility (0-100) per model. It distinguishes itself from sibling tools by focusing on AI visibility scoring, not just answering questions or scanning competitors.

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

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

The description explicitly mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and provides guidance on model selection (default free Workers AI, optional Anthropic with API key). It lacks explicit when-not-to-use advice 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.

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes the tool's behavior: Pipeworx selects the data source and fills arguments automatically. However, it lacks details on limitations (e.g., rate limits, data source availability, error handling) or response format, which are important for a tool with no output schema. The description adds value but is incomplete for behavioral transparency.

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 concise, with three sentences that each serve a purpose: stating the tool's function, explaining its advantage, and providing examples. There is no wasted text, and key information is front-loaded, making it efficient for an agent to parse.

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

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

Given the tool's complexity (natural language processing with automatic tool selection) and lack of annotations and output schema, the description is moderately complete. It explains the core functionality and usage but omits details on output format, error conditions, or data source constraints, which are important for contextual understanding. The examples help, but gaps remain.

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

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

The input schema has 100% description coverage, with the 'question' parameter documented as 'Your question or request in natural language.' The description reinforces this by stating 'Ask a question in plain English' and providing examples, adding context about the expected format. Since schema coverage is high, the baseline is 3, but the description enhances understanding with practical examples, justifying a higher score.

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

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

The description clearly states the tool's purpose: 'Ask a question in plain English and get an answer from the best available data source.' It specifies the verb ('ask'), resource ('answer'), and mechanism ('Pipeworx picks the right tool, fills the arguments'), distinguishing it from sibling tools like 'discover_tools' or 'recall' which likely have different functions.

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: 'No need to browse tools or learn schemas — just describe what you need.' It indicates when to use this tool (for natural language queries) versus alternatives (implying other tools might require browsing or schema knowledge), and includes examples like 'What is the US trade deficit with China?' to 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?

Beyond annotations (readOnly, idempotent, etc.), the description details the extraction-only approach, explicit refusal reasons, and cost of an extra LLM call. 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?

Every sentence adds value: front-loads core concept, explains mechanism, return format, use cases, and trade-off. No redundant or vague phrasing.

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

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

Given the complexity (multiple aliases, high-stakes usage, numerous siblings), the description fully covers purpose, mechanism, inputs, outputs, failure modes, and distinction from siblings. Output format is detailed despite no formal output schema.

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

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

Schema coverage is 100%, so the description adds little beyond stating that the question is in natural language and accepts aliases, which is already in the schema. The description's main value is in tool behavior, not parameter details.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads', explaining the routing and extraction process. It distinguishes from sibling 'ask_pipeworx' by emphasizing groundedness and structured refusal.

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

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

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on' and advises 'prefer ask_pipeworx for casual lookups', 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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes well beyond annotations by detailing resolver confidence levels, parent event extraction, news fallback mechanisms, safety for low-confidence matches, and handling of closed markets. No contradictions found.

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

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

The description is lengthy but information-dense. It is front-loaded with the core purpose and organized into clear sections (classifiers, fan-out examples, response shapes, etc.). Every section adds value, though some simplification could be made. Score 4 for being well-structured but slightly long.

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 and no output schema, the description thoroughly explains the output shapes: market fields (best_bid, best_ask, etc.), analysis fields (model_probability, edge_pp, etc.), evidence keyed by source, resolver contract (match confidence, score, alternatives, suggestions), parent event extractor, and news fields. Edge cases (low confidence, closed markets, wide spreads) are covered.

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

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

Schema coverage is 100% with parameter descriptions. The description adds significant value by explaining the 'quick vs thorough' depth, the include_raw toggle with size implications, and the market parameter flexibility (slug, URL, question text). This enriches the schema 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 the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies multiple input formats (slug, URL, question) and provides explicit use cases ('Use for "should I bet on X"...'). The description distinguishes the tool from siblings by its comprehensive 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 explicitly states when to use the tool ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides detailed examples of fan-outs per classifier. It does not explicitly mention when not to use it or list alternatives, but the context is clear. Score 4 for clear context without 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?

No annotations are provided, so the description fully carries the burden. It discloses return format (paired data + URIs) and the high-level data fields for each type. It does not mention idempotency or side effects, but as a read operation this is acceptable.

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

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

Two sentences with no wasted words. The purpose and key details are front-loaded. Every sentence adds essential information.

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

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

Despite no output schema, the description covers the return format, parameter details, and use case. It is fully adequate for an AI agent to select and invoke the tool correctly.

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

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

Input schema has 100% coverage, but the description adds significant value by explaining the meaning of each field (e.g., revenue, net income for companies; adverse-event reports for drugs) and the expected format (tickers/CIKs vs. drug 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 compares 2–5 entities side by side, specifying distinct fields for company and drug types. It differentiates itself from sequential calls and provides concrete output 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?

The description explicitly recommends this tool to replace 8–15 sequential agent calls, giving clear context for when to use it. It does not provide explicit when-not scenarios, but the efficiency gain is well highlighted.

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

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

Discloses key behaviors beyond annotations: never invents (explicit gaps[]), returns structured findings with verbatim evidence, confidence, source, citations, and typical timing (15-60s). Annotations confirm idempotent, read-only, destructive=false, which description complements.

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

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

The description is reasonably concise given the complexity; it front-loads the core concept and uses clear sentences. Minor reduction possible but every sentence serves a purpose.

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

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

Despite lacking an output schema, the description thoroughly explains what is returned (structured findings, evidence, gaps). Combined with annotations and parameters, it provides a complete picture 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?

With 100% schema coverage, baseline is 3. Description adds value by explaining the meaning of depth options ('quick=3, standard=5, thorough=8') and clarifying that broad/multi-part questions are fine for the question parameter.

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

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

The description clearly states 'Grounded multi-source research in ONE call' and explains decomposition and parallel execution. It distinguishes itself from the sibling 'ask_pipeworx' for single lookups, making the purpose unambiguous.

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

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

Explicitly specifies when to use (broad/multi-part questions) and when not to (use ask_pipeworx for single lookups). Also mentions prerequisites like Pipeworx account and paid plan for 'thorough' depth, providing clear guidance.

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

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

With no annotations provided, the description carries full burden of behavioral disclosure. It effectively describes the tool's behavior: it's a search operation that returns relevant tools based on natural language queries. However, it doesn't mention potential limitations like rate limits, authentication requirements, or error conditions that would be helpful for a search tool.

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 perfectly concise with two sentences that each serve distinct purposes: the first explains what the tool does, the second provides usage guidance. Every word earns its place with no redundancy or unnecessary 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?

For a search tool with no output schema, the description provides good context about what the tool returns ('most relevant tools with names and descriptions'). However, it doesn't specify the format or structure of the returned data, which would be helpful since there's no output schema. The guidance about when to use the tool is excellent contextual information.

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, so parameters are well-documented in the schema. The description doesn't add any additional parameter semantics beyond what's in the schema, but the schema already provides good documentation for both parameters (query and limit).

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 with specific verbs ('search', 'returns') and resources ('Pipeworx tool catalog', 'most relevant tools with names and descriptions'). It distinguishes this tool from its siblings (get_comic, get_latest, random_comic) by focusing on tool discovery rather than comic retrieval.

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: 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task.' This gives clear context about the appropriate scenario (large tool catalog) and positioning (first step in workflow).

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral details beyond annotations: it fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF; returns specific fields; and notes that patents soft-fail (USPTO PatentsView API sunset May 2025). This provides useful context 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, starting with use-case examples and a clear purpose statement, then detailing the fan-out and return fields. It is slightly lengthy but packs necessary information. It could be more concise by avoiding repetition of schema documentation, but overall it is organized and front-loaded.

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

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

Despite no output schema, the description thoroughly explains what the tool returns: cik, company_name, recent_filings with URIs, fundamentals (sorted), patents with fallback, news via GDELT→GNews fallback, and LEI via GLEIF. It also covers limitations (names not supported, patent soft-fail). For a complex multi-source tool, this 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 description coverage is 100% with both parameters already documented in the input schema (including examples and name restrictions). The description repeats these details almost verbatim, adding little new semantic value beyond usage examples. Baseline 3 is appropriate as the schema already provides sufficient parameter documentation.

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 multiple example queries ('Tell me about X', 'research Acme', etc.) and explicitly contrasts with chaining single-pack lookups. It also distinguishes from sibling tools by 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?

The description explicitly tells when to use this tool ('when the user asks for a holistic view') and when not to use it ('names not supported - use resolve_entity first'). It provides a clear alternative (prefer over chaining single-pack lookups) and explains the fan-out behavior across multiple sources.

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?

With no annotations provided, the description carries full burden for behavioral disclosure. 'Delete' implies a destructive mutation, but the description doesn't specify whether deletion is permanent, requires specific permissions, or what confirmation/response to expect. It lacks critical behavioral context for a destructive operation.

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, efficient sentence with zero wasted words. It's front-loaded with the core action and resource, making it immediately scannable and appropriately sized for a simple tool.

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

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

For a destructive tool with no annotations and no output schema, the description is insufficient. It doesn't explain what constitutes a 'stored memory', how keys are structured, what happens on success/failure, or return values. The context demands more completeness for safe usage.

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 the single 'key' parameter adequately. The description adds no additional meaning beyond what's in the schema (both state it's the 'memory key to delete'), meeting the baseline for high 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 ('Delete') and the resource ('a stored memory by key'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'recall' or 'remember', which likely involve memory retrieval/creation rather than deletion.

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 no guidance on when to use this tool versus alternatives. With siblings like 'recall' (likely retrieving memories) and 'remember' (likely storing memories), there's no indication of prerequisites, when deletion is appropriate, or what happens if the key doesn't exist.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds concrete behavioral context: fetching the page, extracting title/description/key links, and emitting standard markdown. This goes beyond annotations to explain network access and processing.

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

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

The description is three sentences long, front-loaded with the core purpose, and every sentence adds value: what it does, how it works, and when to use it. No redundant or irrelevant 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?

For a simple tool with two parameters and no output schema, the description covers all necessary aspects: purpose, process, output format, and use cases. An agent can correctly invoke the 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% and describes both parameters (url, max_links) fully. The description does not add new parameter-specific details beyond the schema, but it provides general context about what the tool does with the URL (fetch, extract). Baseline 3 is appropriate as the description does not degrade understanding.

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

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

The description clearly states the tool generates an llms.txt file for any URL, specifying the AI crawlers and output format. It lists specific use cases (client indexing, personal projects, competitor auditing) that differentiate it from sibling tools like scan_competitor_ai_presence.

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

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

The description provides explicit use cases in the 'Useful for' section, giving clear context for when to invoke the tool. It does not explicitly state when not to use it or list alternative tools, but the sibling list includes related tools, and the use cases are sufficient for 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool's purpose but does not describe behavioral traits such as whether it's read-only, potential rate limits, error handling, or response format. This leaves significant gaps for a tool with no annotation coverage.

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

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

The description is a single, efficient sentence that front-loads the core purpose without any wasted words. It is appropriately sized for a simple tool, making it easy to understand at a glance.

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 lack of annotations and output schema, the description is incomplete. It does not address behavioral aspects like safety, performance, or return values, which are crucial for an AI agent to use the tool effectively. For a tool with no structured data support, more context is needed.

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, fully documenting the single parameter 'number'. The description adds no additional parameter semantics beyond what the schema provides, such as validation rules or examples. With high schema coverage, the 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 specific action ('Get') and resource ('a specific XKCD comic by its number'), distinguishing it from sibling tools like 'get_latest' and 'random_comic' which serve different purposes. It precisely communicates the tool's function without ambiguity.

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 implicitly suggests usage when a specific comic number is known, but it does not explicitly state when to use this tool versus alternatives like 'get_latest' or 'random_comic'. It provides clear context for its use case but lacks explicit exclusions 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?

No annotations are provided, so the description carries the full burden. It describes what data is returned (title, image, alt text) and that it fetches the 'latest published' comic, which adds useful context. However, it lacks details on potential errors, rate limits, or network behavior, leaving gaps in behavioral disclosure for a tool with no annotation coverage.

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

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

The description is a single, efficient sentence that front-loads the key information: the action, resource, and returned data. There is no wasted text, and it is appropriately sized for a simple tool with no parameters.

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 (0 parameters, no output schema, no annotations), the description is largely complete for its purpose. It specifies what data is returned, which compensates for the lack of output schema. However, it could be more complete by mentioning potential limitations or errors, though this is a minor gap for such a straightforward tool.

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

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

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately does not discuss parameters, focusing instead on the tool's purpose and output. This meets the baseline for tools with no parameters, as it adds value without redundancy.

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 specific action ('Get') and resource ('latest published XKCD comic'), including the exact data returned ('title, image, and alt text'). It distinguishes from siblings by specifying 'latest' versus 'get_comic' (likely by ID) and 'random_comic' (random selection).

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 context by specifying 'latest published' comic, suggesting it's for retrieving the most recent one. However, it does not explicitly state when to use this tool versus alternatives like 'get_comic' or 'random_comic', nor does it mention any exclusions or prerequisites.

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 destructiveHint. The description adds value by detailing return fields (id, type, params, created_at, last_fired_at, fire_count) and default behavior (active only, optional include_inactive). No contradictions.

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

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

Two sentences with no waste. The first sentence states purpose and return fields, the second gives usage guidance. Perfectly 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?

Given low complexity (1 optional boolean, no output schema), the description covers purpose, return fields, default behavior, and usage context. It is complete for an agent to decide and 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 covers the parameter (include_inactive) with 100% coverage. The description implicitly connects it to active vs. inactive subscriptions but does not add explicit parameter documentation beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with specific verb and resource. It distinguishes from sibling tools 'subscribe' and 'unsubscribe' by focusing on listing current subscriptions.

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

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

The description provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use the tool, though it does not explicitly exclude other scenarios.

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?

No annotations provided, so description carries full burden. It discloses rate limit (5 messages per day) and that it's free, but does not describe the result or expected outcome after sending feedback.

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, each with distinct purpose: purpose, use cases, content guidelines, rate limit. No redundancy or 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 feedback tool with no output schema, the description covers purpose, when to use, content guidelines, and rate limits. 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 covers 100% of parameters with descriptions, so baseline is 3. Description adds value with guidance on message content (not including user prompt), but does not significantly enhance type or context semantics 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 'Send feedback to the Pipeworx team' and lists specific use cases (bug reports, feature requests, etc.), which distinguishes it from sibling tools like ask_pipeworx or get_comic.

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 (bug reports, feature requests, etc.) and provides content guidelines ('Describe what you tried... do not include end-user prompt'). Context with siblings makes alternatives clear, though no explicit 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 safe, but description adds self-aggregating signal, no PII, and caching details (5min-1h). 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?

Front-loaded with clear statement, but slightly verbose with bullet points. Still efficient and 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?

Simple tool fully described: what, when, cache. No output schema needed. Complete 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 coverage 100% with good description. Overall description reinforces window meaning, adding richness 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 'returns' with specific resource: top tools, top packs, call volume over windows. Distinct from siblings like discover_tools or 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 lists three use cases: discovering hot data sources, confirming canonical choice, aligning use case. Provides clear context for when to use.

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

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

Annotations already declare safe read-only behavior, but the description adds substantial detail: partition_check computation, monotonicity verification, Jaccard similarity for cross-event, placeholder filtering, and response structure. 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 and front-loaded with the requirement and main purpose. While not concise, every sentence adds value, and the structure clearly separates event and topic modes. Minor verbosity 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?

Despite lacking an output schema, the description fully details the response fields (opportunities array with gap_pp, suggested_trade, reasoning, etc.) and partition_check object. It covers modes, requirements, and edge cases, 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% with parameter descriptions, but the tool description adds significant meaning: example slugs, explanation of what each mode does, partition_check details, and filtering logic. This greatly aids correct parameter usage.

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

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

The description clearly states the verb 'Find' and the resource 'arbitrage opportunities on Polymarket', and specifies the method 'monotonicity violations + partition-sum checks'. It distinguishes two modes (event and topic), differentiating it from sibling tools like polymarket_edges and polymarket_kalshi_spread.

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 one of 'event' or 'topic', recommends event for specific markets, and topic for cross-event scanning. It explains what each mode does and what cross-event catches that single-event misses, providing clear when-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds significant behavioral context beyond these, including detailed model family explanations, edge calculation (edge_pp_net after slippage), Kelly fractions, diagnostics (filter skips), caching behavior ('Cached 1h at the KV level'), and Fed-market caveats. It covers what the tool does internally without repeating annotation values.

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

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

The description is dense and structured with numbered segments and clear section headers, but it is very long (multiple paragraphs). While front-loaded with the core purpose, it includes extensive model-family details that could be compressed for faster agent parsing. Every sentence adds value, but the length risks overwhelming a token-limited agent context.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is exceptionally complete. It explains the full response structure (by_segment, fed_candidates, _diagnostics), caching, edge cases like Fed markets, and tradeability knobs. It even notes why certain filters exist (e.g., placeholder-slug filter, partition skipping). This fully compensates for the missing output schema, making it highly actionable 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%, so the schema already documents all 9 parameters. The tool description adds some behavioral context (e.g., min_partition_leg_kelly explains that partition arbs return kelly_fraction_half=0 and why min_kelly doesn't filter them). However, most parameter descriptions in the schema are already fairly detailed, so the description adds only incremental value, justifying a baseline-adjacent score.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the output segments and uses a memorable tagline 'what should I bet on today.' However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage, which slightly reduces clarity in a crowded toolset.

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 implicit usage context ('Built for what should I bet on today') and details knobs like min_liquidity and max_spread_pp for tradeability. However, it lacks explicit guidance on when not to use this tool or alternatives (e.g., polymarket_arbitrage for pure arbitrage), leaving the agent to infer boundaries.

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 substantial behavioral context: limits (60-day TTL, from enablement date), decay computed from daily closes not intraday, and detailed response structure. No contradictions.

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

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

The description is verbose but well-structured with sections for goal, args, response, and limits. It could be more concise without losing clarity, but the front-loaded question helps.

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

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

No output schema exists, so the description fully explains the response structure: tracked[], expired[], snapshot_dates[]. It also covers limits and data sources, making it complete for an agent to understand what the tool returns.

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 extra context: for 'days' it mentions max 30 (schema clamps 2-30), for 'window' it specifies 'snapshot family' and default '1wk'. This adds value beyond the schema.

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

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

The description explicitly states the tool's purpose: 'Edge persistence and decay telemetry' answering 'how long has this edge existed and is it shrinking?' It clearly distinguishes from the sibling 'polymarket_edges' by focusing on temporal tracking rather than raw edge 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 provides context on when to use the tool, e.g., 'a fresh wide edge and a 3-week-old wide edge are different trades.' It implies usage for differentiating new vs. old edges but does not explicitly state when not to use it or mention alternative 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?

The description adds substantial behavioral context beyond the annotations (readOnlyHint, openWorldHint, idempotentHint). It explains the tool walks the order-book ladder, returns verdicts (clean|degraded|cannot_fill), and explicitly warns about the risk of partial basket fills. 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 with clear sections for single-market and basket modes. Every sentence adds value, though it could be slightly more concise without losing 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?

With no output schema, the description compensates by enumerating all return fields for both modes. It covers edge cases (thin legs, forced directional risk) and explains the dominant loss mode. The description is fully complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds meaning by explaining the 'side' parameter's auto-default in basket mode, and clarifies 'size_usd' as settlement notional for baskets. This goes beyond the schema definitions.

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

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

The description clearly states the tool performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes, with specific outputs listed. It explicitly differentiates itself from sibling tools by recommending usage before polymarket_arbitrage or polymarket_edges trades above ~$500.

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: before acting on arbitrage signals or edge trades above $500. It also explains the consequences of not using it (partial fills converting arb into unhedged directional position). It clarifies requirements: one of 'market' or 'event' must be 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?

The description extensively discloses behavioral traits beyond the annotations (readOnlyHint, etc.), including safety fields like compatibility_warning, temporal_alignment, and skipped_cross_type counters. It explains edge cases where spreads are meaningless, providing thorough transparency.

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 clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. While relatively long, every sentence adds value for a complex tool; however, minor tightening 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 complexity (3 optional parameters, no output schema), the description is remarkably complete. It covers response format, safety fields, compatibility warnings, and temporal alignment, leaving no significant gaps for an agent to understand 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 the description adds contextual meaning: it explains the two modes and how explicit parameters override topic-mapped sides. It also provides example values, which 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 the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit pairing) and distinguishes from sibling tools like polymarket_arbitrage (intra-venue) by emphasizing its cross-venue nature.

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

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

The description explains two modes of use and warns that most pre-mapped topics return compatibility warnings, implying when the tool is reliable. However, it does not explicitly state when not to use the tool or list alternative tools for intra-venue analysis, so guidance on alternative selection is implicit rather than explicit.

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?

No annotations are provided, so the description carries full burden. It states what the tool does but doesn't disclose behavioral traits such as rate limits, error handling, or response format. The description is minimal and doesn't add context beyond the basic operation.

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, efficient sentence that directly states the tool's purpose without any wasted words. It is appropriately sized and front-loaded, making it easy to understand quickly.

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

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

Given no annotations and no output schema, the description is incomplete for a tool that likely returns comic data. It doesn't explain what is returned (e.g., image URL, title, metadata), leaving gaps in understanding the tool's behavior and output.

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

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

There are 0 parameters, and schema description coverage is 100%, so no additional parameter information is needed. The description doesn't add param details, but with no parameters, this is acceptable, aligning with the baseline for zero parameters.

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 ('Get') and resource ('a random XKCD comic from the full archive'), specifying it's random and from the full archive. This distinguishes it from siblings like 'get_comic' (likely specific) and 'get_latest' (most recent).

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

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

The description implies usage for retrieving a random comic, but doesn't explicitly state when to use this tool versus alternatives like 'get_comic' or 'get_latest'. It provides context (random, full archive) but lacks explicit guidance on exclusions or comparisons.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: retrieving stored memories by key or listing all keys, and clarifies persistence across sessions ('saved earlier in the session or in previous sessions'). It doesn't mention error handling or performance characteristics, but covers core functionality well.

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

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

The description is perfectly concise and well-structured in two sentences. The first sentence states the dual functionality, the second provides usage context. Every word earns its place with zero redundancy or fluff.

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

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

For a tool with no annotations and no output schema, the description provides good contextual completeness. It explains what the tool does, when to use it, and how parameters affect behavior. It could benefit from mentioning the return format (e.g., memory content vs. key list), but otherwise covers the essentials well.

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 has 100% description coverage, so the baseline is 3. The description adds significant value by explaining the semantic meaning of omitting the key parameter ('omit to list all keys'), which clarifies the dual functionality beyond what the schema's technical description 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 with specific verbs ('retrieve', 'list') and resources ('previously stored memory', 'all stored memories'), and distinguishes it from sibling tools like 'remember' (store) and 'forget' (delete). It explicitly mentions retrieving context saved earlier in sessions.

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 to retrieve context you saved earlier in the session or in previous sessions' establishes the primary use case. It also specifies when to omit the key parameter ('omit key to list all keys'), giving clear operational instructions.

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 claims mark_read:true flags returned events as read, which modifies state, but annotations declare readOnlyHint=true. This is a direct contradiction. Additionally, the description does not disclose rate limits or other behavioral traits beyond what annotations already 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 three sentences, front-loaded with the primary purpose. Every sentence adds value: first states function, second details response content and filtering, third explains mark_read and alternative access. 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, the description adequately explains what each alert carries (source, citation_uri, raw payload). It covers filtering, mark_read behavior, polling suitability, and the external endpoint. Missing details about shared state across users or feed persistence, but overall sufficient for a simple read tool.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds extra context beyond the schema by providing examples ('sec_8k'), clarifying that since expects an ISO timestamp, and explaining the side effect of mark_read. This adds meaningful usage guidance.

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 pulls fired events from the subscription feed and returns alerts with specific fields. It uses specific verbs and resources ('Pull fired events', 'returns alerts') and distinguishes the tool from siblings by noting the alternative HTTP endpoint for scripts, implying this is the programmatic/AI interface.

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

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

The description mentions polling works fine and provides an alternative HTTP endpoint for scripts, but does not clearly state when to use this tool versus other sibling tools like search_within or list_subscriptions. No explicit when-not-to-use or exclusion criteria are 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 indicate readOnly, idempotent, non-destructive. Description adds rich behavioral details: fans out to SEC, GDELT→GNews fallback, USPTO soft-fail, returns structured output with citation URIs. No contradictions.

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

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

Concise 6-7 sentences, front-loaded with examples, no wasted words. Each sentence provides necessary 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 no output schema, description fully covers return structure. Handles complexity of multiple sources, fallback logic, parameter details. Agent has all needed context.

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

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

Schema coverage is 100%, but description adds meaning: explains type limitation (only company), since format options with recommended defaults, value accepts ticker or CIK. Also warns about USPTO soft-fail.

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 provides a change feed for a company over a time window, with examples like "What's new with X". It distinguishes from sibling tool entity_profile by specifying when to use that instead.

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 entity_profile for static profile. Provides context on when to use this tool for recent changes, though it could be more explicit about when not to use it beyond the one alternative.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the persistence difference between authenticated users ('persistent memory') and anonymous sessions ('last 24 hours'), and the cross-tool context capability ('across tool calls'). However, it doesn't mention potential limitations like storage capacity or rate limits.

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 perfectly concise with two sentences that each earn their place. The first sentence states the core purpose, the second adds crucial behavioral context about persistence differences. No wasted words, and the most important 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 2-parameter tool with no annotations and no output schema, the description provides good contextual completeness. It explains what the tool does, when to use it, and key behavioral aspects. The main gap is the lack of information about return values or error conditions, which would be helpful given there's no output schema.

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

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

With 100% schema description coverage, the schema already documents both parameters thoroughly. The description doesn't add meaningful parameter semantics beyond what's in the schema - it mentions 'key-value pair' generically but doesn't provide additional context about parameter usage, constraints, or examples beyond the schema's 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 with specific verb ('Store') and resource ('key-value pair in your session memory'), distinguishing it from siblings like 'recall' (retrieve) and 'forget' (delete). It explicitly mentions what can be stored ('intermediate findings, user preferences, or context across tool calls'), providing concrete 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?

The description provides clear context for when to use the tool ('to save intermediate findings, user preferences, or context across tool calls'), but doesn't explicitly mention when not to use it or name specific alternatives. It distinguishes from 'recall' by implication (store vs. retrieve) but doesn't explicitly compare with other siblings.

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

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

No annotations are provided, so the description carries the full burden. It accurately describes the operation as a single call resolving entities, but lacks details on side effects, authentication, or error handling, though for a resolution tool this is acceptable.

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, front-loaded with the main action, and includes key details without redundancy. 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?

Given no annotations or output schema, the description sufficiently covers the tool's purpose, inputs, outputs, and use-case (replacing multiple calls). The tool is simple, and the description 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 description coverage is 100%, and the description adds value by providing examples and stating the return format. It does not repeat the schema but enhances it with context about the return and the purpose of each parameter.

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

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

The description clearly states the tool resolves an entity to canonical IDs, gives specific examples for type and value, and mentions the return values including ticker, CIK, company name, and resource URIs. This is a specific verb+resource 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 explains that it replaces 2-3 lookup calls, implying efficiency gains over alternative approaches. However, it does not explicitly contrast with sibling tools like ask_pipeworx or 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?

Description adds internal delegation to ai_visibility_check, ranking logic, and output fields (score, confidence, signal density). Annotations (readOnlyHint, idempotentHint) are consistent and do not contradict. No behavioral gaps.

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, front-loaded with purpose and outcome. No wasted words, though could slighty reduce redundancy (e.g., 'probes each entity' repeated). Efficient 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?

Complexity moderate (4 params, no output schema). Description covers operation, internal flow, and result structure. No missing critical details for agent invocation.

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

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

Schema coverage is 100%, but description adds meaningful context: 'First entry treated as subject for narrative', notes default model and API key requirement. Adds value beyond schema definitions.

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 ('Compare AI visibility'), specific resource ('multiple entities'), and distinguishing detail ('probes each entity with ai_visibility_check, ranks by score'). Distinguishes from sibling 'ai_visibility_check' (single) and 'compare_entities' (generic).

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 use case ('competitive AI-marketing audits') and example question. Does not explicitly state when not to use, but contrasts with single-entity probe sibling. Lacks strict 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?

Beyond annotations (readOnly, idempotent, openWorld), the description discloses partial failures, timeout behavior for bundlephobia first measurement, and the graceful degradation with a 'sources_failed' key. 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 long but well-structured with clear front-loading of purpose, then details on usage, behavior, and ecosystem limitations. Each sentence adds information, though some brevity 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 complexity and lack of output schema, the description covers return format (summary block, advisories, links, alternatives), ecosystem scope, and partial failure handling. It is largely complete, though error handling beyond timeouts is not detailed.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that version defaults to latest when omitted and that scoped packages are accepted, which slightly exceeds 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 specifies the tool as a composite check for npm packages, detailing the exact purpose ('should I add this npm package'), the services it uses (deps.dev and bundlephobia), and the data it returns. It clearly distinguishes from siblings by being a multi-source composite.

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 ('is X safe / popular / small' or 'what does adding lodash cost me') and notes the ecosystem limitation (NPM only, with alternatives for other ecosystems). It does not mention sibling tool names for comparison, but the provided context has them.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds valuable behavioral details: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, capped at 200K chars with truncation and flagging. Also notes that returned passages include character offsets and similarity scores, which helps the agent verify quotes.

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 concise. It front-loads the purpose and usage context, then provides technical details. Every sentence adds information without redundancy. The length is appropriate for the complexity of the tool.

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

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

Given the complexity of semantic search with embedding models and windowing, the description covers return values (passages, offsets, scores), limitations (200K char cap, truncation), and internal mechanics. No output schema exists, but the description compensates adequately.

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

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

Schema description coverage is 100%, so baseline is 3. The description enriches parameters by explaining 'text' is the document to search, 'query' is a natural-language query with examples, and 'limit' controls max passages. This adds meaning beyond the schema's brief 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 performs semantic search inside a fetched record. It specifies the action ('search inside a fetched record'), the resource ('the text you already pulled'), and distinguishes from siblings like ask_pipeworx_grounded by explaining how they pair together.

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

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

The description explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also suggests pairing with ask_pipeworx_grounded. However, it does not explicitly mention when not to use it or provide alternatives for small records, but the context is clear enough for an AI agent.

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

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

The description discloses auth requirements, type-specific parameters, and channel limitations (SMS cap, webhook auto-disable). Annotations declare idempotentHint=true, but the description does not elaborate on idempotency; still, no contradiction and good added 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 lengthy but well-structured: starts with the core action and result, then prerequisites, then types and delivery details. Every sentence adds value, though it 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?

Given the complexity (3 parameters, 5 enum types, nested delivery object), the description covers types, params, and delivery constraints adequately. It mentions return value but lacks error handling details. Output schema is absent, but the return value is stated minimally.

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

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

The description adds substantial meaning beyond the input schema: it explains type semantics (e.g., sec_8k items codes), gives example params for each type, and details delivery channel properties (phone verification, rate limits, webhook signing). Schema coverage is 100%, but the description enriches this further.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' and mentions returning a subscription ID, distinguishing it from sibling tools like 'list_subscriptions' (read) and 'unsubscribe' (delete).

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 specifies prerequisites (Pipeworx OAuth account), supported types with examples, and delivery channel constraints. It does not explicitly state when not to use, but the context is clear enough for an agent to decide.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds that the tool returns example questions with exact tool+argument shapes from the live catalog, providing useful behavioral context 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 starts with common user queries, then states purpose, describes output, and gives usage guidance. It is slightly lengthy but well-structured and front-loaded, with no wasted sentences.

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 one optional parameter, no output schema, and rich annotations, the description is fairly complete. It explains purpose, when to use, parameter details, and hints at output structure, though could mention the output format more explicitly.

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

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

Schema coverage is 100%. The description explains the optional topic parameter, lists possible values, and clarifies behavior when omitted (full spread vs. focused), adding meaning beyond the schema's basic 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 it is the onboarding entry point, explains it returns category-bucketed example questions, and distinguishes from siblings like ask_pipeworx by specifying it is the first tool to use when unsure about Pipeworx capabilities.

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

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

Explicitly advises to use this tool FIRST when the user does not know what Pipeworx can do, or to learn how to call meta-tools. It also describes the optional topic parameter to narrow results. No explicit when-not-to-use, but the purpose is well-defined.

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, destructiveHint=false. The description adds value beyond annotations by explaining that the row is deactivated (not deleted) and historical events remain available, disclosing the actual behavioral effect.

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 short sentences with no unnecessary words. Essential information is front-loaded: the action and the key constraints.

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

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

For a simple tool with one required parameter and no output schema, the description fully covers behavior, constraints, and side effects. Annotations provide the rest of the behavioral context. No gaps.

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

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

The input schema has one parameter 'id' with description 'Subscription id (uuid) returned by subscribe.' The description adds ownership context but doesn't provide additional parameter details beyond what the schema already covers. Schema coverage is 100%, so baseline is 3.

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

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

The description clearly states 'Cancel a subscription by id.' The verb 'cancel' and resource 'subscription' are specific. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description mentions ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for use. However, it doesn't explicitly state when not to use it or name alternatives, but the context is sufficient for an agent.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive. The description adds that it returns a verdict, structured form, actual value with citation, and percent delta, and that it replaces sequential calls. 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, front-loaded with trigger phrases and scope. Every sentence provides value with no wasted words.

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

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

Given the tool has only one parameter, full schema coverage, and no output schema, the description is complete: it explains purpose, usage, return values, 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?

The input schema covers the single 'claim' parameter with a description. The tool description does not add additional meaning beyond what the schema provides. Schema coverage is 100%, 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 it performs natural-language claim verification against authoritative sources, listing trigger phrases and specifying the scope (company-financial claims). It distinguishes from sibling tools by noting it replaces 4-6 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 to use whenever the agent needs to check factual correctness, and scopes it to company-financial claims. While it doesn't explicitly say when not to use, the context from sibling tools makes it clear.

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