Schrodingers Boolean

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the tool is safe. Beyond annotations, the description adds behavioral context: returns per-model {score, confidence, signals, raw_response} + combined view, and mentions cost implications (free default, Anthropic requires BYO key). No contradictions.

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

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

Description is concise—two sentences plus a use-case sentence. It front-loads the main action (probe and score), then details optional behavior and return format. Every sentence adds value without redundancy.

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

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

For a tool with 4 parameters (1 required), no output schema, and no nested objects, the description is complete. It covers the primary function, input parameters (with examples), return structure, and use cases. No gaps remain for an agent to correctly select or 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 description coverage is 100%, so parameters are well-documented. The description adds contextual value by explaining the default model, the purpose of the '_apiKey' (BYO key for Anthropic), and how 'context' helps disambiguate. This enhances understanding beyond the schema descriptions.

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

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

Description clearly states the tool probes LLMs for visibility of a brand/business/product/topic and scores it (0-100). It distinguishes from siblings by specifying the probe-and-score function, default model, and optional Anthropic, which differentiates it from tools like 'scan_competitor_ai_presence' that may have a narrower focus.

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

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

Description explains usefulness for AI-marketing audits, pre-launch checks, and competitive monitoring. It also clarifies when to use the Anthropic model (requires _apiKey). However, it does not explicitly state when not to use this tool versus alternatives, such as when grounded search is needed (e.g., ask_pipeworx_grounded).

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

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

Annotations already declare the tool is read-only, idempotent, and not destructive. The description adds that it routes to 3,751 tools and returns structured answers with citation URIs, providing some behavioral context. However, it does not disclose potential latency, required permissions, or failure modes, which would be helpful given the complexity.

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 moderately concise but includes redundant examples and slightly verbose language (e.g., listing many query types). It could be tightened without losing clarity, but it is still functional and front-loaded with the key guidance.

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 return structure ('structured answer with stable pipeworx:// citation URIs') and provides extensive examples. It covers the tool's scope, input usage, and outcome, making it reasonably complete for a read-only query tool with one required parameter.

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 6 parameters all aliases for 'question', with 100% description coverage. The description adds minimal additional meaning beyond that the question should be in natural language and that the tool routes it to appropriate sources. With high schema coverage, the description's contribution is marginal, earning a baseline score of 3.

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

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

The description clearly states the tool's function: answering factual queries about real-world entities and data by routing to thousands of verified sources. It uses specific verbs like 'ask' and contrasts with web search. Sibling tools like 'ask_pipeworx_grounded' exist, but the description distinguishes itself by specifying its broad scope and preference over web search.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and lists numerous query types and example questions, providing strong guidance on when to use the tool. However, it does not mention when not to use it or compare it to sibling tools like 'deep_research' or 'ask_pipeworx_grounded', which could provide clearer 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 already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds behavioral details: returns explicit refusal reasons on failure, extracts answer only from tool result, and costs 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?

Description is a single paragraph that efficiently covers purpose, process, return format, and trade-offs. Each sentence adds value, though it could be broken into shorter sentences or bullet points for easier consumption.

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

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

Given no output schema, the description explains the exact return structure including fields like answer, evidence, refusal_reason, etc. It covers failure modes, use cases, and comparison with sibling. Completeness is high for a tool with 6 parameters and high stakes.

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

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

Schema coverage is 100% with all parameters documented. Description adds value by listing all aliases (q, text, input, query, prompt) and clarifying that the parameter accepts natural language questions. Provides clear, complete parameter semantics.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and explicitly differentiates from sibling 'ask_pipeworx' by noting extra LLM call cost and specific use cases for quoted/cited answers.

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: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and when not to: 'prefer ask_pipeworx for casual lookups.' Also lists example domains (financial verdicts, legal claims, medical lookups, public statements).

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: parallel fan-out, response shapes (market, analysis, evidence), resolver contract (market_match_confidence, alternatives, suggestions), parent event extractor, news fields with fallback behavior, safety checks (low-confidence shuts down analysis), and resolution-rule risk. Annotations already indicate readOnly, idempotent, openWorld, non-destructive; the description adds rich context without contradiction.

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

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

The description is comprehensive but somewhat verbose. It front-loads the main purpose and use cases, then goes into detailed examples and edge cases. Every sentence adds value, but the length could be trimmed for readability. Still, it is well-structured with clear sections.

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

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

Given the tool's complexity (classifiers, fan-out examples, response shapes, edge cases), the description is highly complete. It explains output fields (result.market, analysis, evidence), resolver contract details, parent event extractor, news fallback, safety mechanisms, and resolution-rule risk. Without an output schema, the description fully covers 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%, but the description adds significant meaning beyond the schema: it explains the three types of input for 'market', the distinction between 'quick' and 'thorough' for 'depth', and when to use 'include_raw' (false is recommended for size, true for raw payloads). Examples further clarify usage.

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

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

The description clearly states the tool's purpose: research a Polymarket bet by pulling Pipeworx data in one call. It specifies input types (slug, URL, question text) and outlines what the tool does (resolves market, classifies bet, fans out to data packs, returns evidence packet + comparison). The use cases are explicitly listed, distinguishing it from sibling tools like validate_claim or polymarket_edges.

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

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

The description provides explicit use cases ('Use for...') and explains various scenarios (low-confidence matches, closed markets, wide spreads). However, it does not mention when not to use the tool or suggest alternative tools from the sibling list, which would strengthen 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 read-only, non-destructive, idempotent, and open world. The description adds valuable behavioral context: backend data sources (SEC XBRL, FAERS, FDA), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradictions.

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

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

The description is longer than average but every sentence adds essential information: triggers, purpose, data sources, behavior, and efficiency. It is front-loaded with the most critical info. Could be slightly more concise, but no wasted words.

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

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

Given the tool's complexity (2 params, no output schema, multiple data sources), the description is complete. It covers data sources, edge cases (off-calendar fiscal years), sorting behavior, citation URIs, and efficiency gains. No obvious gaps for agent decision-making.

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 meaningful context beyond schemas, including examples (['AAPL','MSFT'], ['ozempic','mounjaro']), value constraints (2-5 items), and the relationship between type and data retrieved.

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

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

The description starts with clear natural language triggers like 'Compare X and Y' and explicitly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It distinguishes from sibling tools like entity_profile by emphasizing efficiency and parallel data 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 gives an explicit usage directive: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It details when to use (comparing entities) and what data each type retrieves, but does not provide specific when-not-to-use or alternatives beyond the efficiency claim.

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 context: parallel execution, verbatim evidence with confidence/source/citation, explicit gaps for unanswered facets, no invention, expected 15-60s response. No contradiction.

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

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

Single paragraph is well-structured, front-loading core functionality then usage and prerequisites. Every sentence is informative, though a list format might improve scannability.

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

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

For a complex tool with no output schema, the description covers all critical aspects: process, output format (findings packet with evidence, gaps), usage, prerequisites, and behavioral constraints. No 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?

Schema coverage is 100%, but description adds value: for 'depth' it clarifies facet counts and paid plan requirement; for 'question' it emphasizes broad/multi-part suitability. These details go beyond schema descriptions.

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

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

The description clearly states it performs grounded multi-source research in one call, decomposing questions into sub-questions and routing to many tools in parallel. It distinguishes itself from siblings like ask_pipeworx, which is for single lookups.

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

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

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

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, destructiveHint=false, idempotentHint=true. The description adds that results include 'names, descriptions, and full input schemas (with curated examples)' and that each result is 'ready to call directly, no second schema lookup needed.' This goes beyond annotations to explain retrieval behavior and format. 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 two sentences: first sentence states purpose and scope, second sentence provides usage guidance and return value details. Every part earns its place, no fluff, front-loaded with key information. Very concise and well-structured.

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

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

The description explains what is returned (top-N tools with names, descriptions, schemas) and how to use it. No output schema exists, but the description covers return value sufficiently. It also provides examples in the input schema. For a discovery tool with 6 parameters, this is complete enough. Lacks only potential failure modes or limit details, but still strong.

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

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

Schema coverage is 100%, so the schema already describes all parameters. The description mentions aliases for query (task, q, description, search) but these are already listed in the parameter descriptions. The description adds no new semantic detail beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many domains (SEC filings, financials, FDA drugs, etc.) and specifies it returns top-N relevant tools. The sibling tools are specific functions, so this discovery tool is distinct. The instruction 'Call this FIRST' further differentiates it.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for:' followed by domains. It also advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implies alternatives are the sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful behavioral details beyond these: it mentions fanning out across multiple sources, the USPTO PatentsView API sunset with soft-fail behavior, and returns specific fields (cik, recent_filings with URIs, fundamentals, etc.). This adds 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 dense but clear, front-loaded with example queries and purpose. It is structured as a single paragraph with enumerated outputs. While some sentences could be more concise, every sentence adds value, making it efficient for a complex 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 tool's complexity—multiple data sources, outputs, and limitations—the description covers inputs, outputs, sources, fallback behavior (USPTO soft-fail), and return fields (filings with URIs, fundamentals sorted, patents, news, LEI). No output schema exists, so the description's explanation of return values is sufficient and complete.

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

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

Schema coverage is 100% and both parameters are described in the schema. The description adds meaning by explaining the 'type' enum is limited to 'company' (with future expansion) and 'value' can be ticker or zero-padded CIK, reiterating that names are not supported. This enhances the schema's definition.

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 action: 'full cross-source profile of a US public company in ONE parallel call.' It lists specific examples ('Tell me about X', 'research Acme') and distinguishes from sibling tools by directing to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and noting to use 'resolve_entity' if only a name is provided.

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 when-to-use guidance is provided via example queries and the directive 'ALWAYS PREFER over chaining...'. It also specifies when not to use: names are not supported, requiring resolution via resolve_entity first. This clearly delineates usage context from alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description adds 'Delete' but no further behavioral context (e.g., idempotency effects, error handling). Adequate but not enhanced.

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

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

Two sentences, no fluff, front-loaded with core action and usage guidance.

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 single parameter, no output schema, and simplicity of task, description covers all needed context: what it does, when to use, and sibling reference.

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

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

Schema coverage is 100% with clear description for 'key'. Description does not add additional 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?

States 'Delete a previously stored memory by key.' Verb and resource are clear, and it distinguishes from siblings like 'remember' and 'recall'.

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

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

Explicitly says when to use ('context is stale, task is done, clear sensitive data') and advises pairing with siblings, providing clear context for selection.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details like fetching the page, extracting title/description/key links, and emitting standard markdown. This complements the annotations without contradicting them.

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

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

The description is three sentences long, front-loaded with the primary use case, and contains no fluff. Minor redundancy like 'production-ready' and 'standard...format' could be streamlined, but overall it is efficient.

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

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

For a simple tool with two parameters and no output schema, the description adequately explains the return format ('single text blob') and common use cases. It does not cover error handling or invalid URLs, but the core functionality is well-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 detailed parameter descriptions. The tool description does not add significant new meaning beyond the schema, such as clarifying default behavior or valid URL formats. Baseline 3 is appropriate given 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 states the specific verb 'generate', the resource 'llms.txt file for any URL', and explains the purpose for AI crawlers. It also mentions the output format, making the tool's function clear and distinctive among siblings 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 lists three concrete use cases (client's site, own project, competitor audit), which provide good context for when to use the tool. However, it does not explicitly exclude scenarios or compare to sibling tools, leaving some ambiguity for edge 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?

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint as false, so the bar is lower. The description adds behavioral context by listing the returned fields and the purpose (review monitoring, find ID to cancel), which is consistent with the annotations.

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

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

The description is two sentences with no wasted words. The first sentence states the action and return fields, the second explains when to use it. 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 the simple tool with one optional parameter and no output schema, the description adequately explains the return fields and the use case. It could mention that the list is scoped to the caller, but the phrase 'caller's' already does that. No major 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?

With 100% schema coverage, the parameter 'include_inactive' is already fully described in the schema. The description adds no further detail about the parameter, so it meets the baseline for this dimension.

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' and lists the return fields. However, it initially says 'active subscriptions' while the parameter can include inactive ones, causing slight ambiguity. The sibling tools (subscribe, unsubscribe) are distinct, so purpose is clear overall.

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

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

The description explicitly advises using this tool before adding more subscriptions or to find an ID to cancel, providing clear when-to-use guidance. It does not explicitly mention when not to use it, but the context is sufficient.

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

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

Description adds behavioral details beyond annotations: 'Rate-limited to 5 per identifier per day' and 'Free; doesn't count against your tool-call quota.' Annotations are all false, and description aligns with them, no contradiction.

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

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

Description is reasonably concise with 4 sentences, each serving a purpose. Front-loaded with main action. Slightly verbose but not wasteful; still clear and structured.

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

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

Given the tool's simplicity (sending feedback) and complete schema/description, the description covers all necessary context: purpose, when to use, rate limits, and parameter semantics. No output schema 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?

Schema coverage is 100%, and description enriches parameter understanding: explains 'type' enum values, advises to 'Describe the issue in terms of Pipeworx tools/packs', and provides length guidance (1-2 sentences, 2000 chars max). Adds significant value beyond schema.

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

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

Description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the resource (Pipeworx team) and actions (bug, feature, data_gap, praise). Unambiguous and distinct from sibling research tools.

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

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

Explicitly provides usage scenarios: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also includes what to avoid: 'don't paste the end-user's prompt.' Mention of rate limit and quota provides clear constraints.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: caching (5min-1h), data source (CF analytics-engine), no PII, and return structure (pack, tool, count).

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 the core purpose in the first sentence, followed by use cases and technical details. Each sentence adds value without redundancy.

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

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

For a simple read-only aggregated data tool with no output schema, the description adequately explains the return format, caching, and data source, making it complete for an AI agent to understand.

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 enum descriptions. The description adds extra semantic value by explaining the trade-off between window lengths ('hot right now' vs 'steady-state demand'), which is not in the schema.

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

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

The description clearly states the tool returns trending tools, packs, and call volume over a window, distinguishing it from siblings like ask_pipeworx or discover_tools by focusing on usage statistics.

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?

Three explicit use cases are provided, giving clear context for when to use the tool. However, it does not mention when not to use it or provide direct alternatives.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description details monotonicity checks, partition-sum logic, Jaccard similarity thresholds, placeholder filtering, fill check with realizable vs theoretical edge, and conditions for actionable signals. 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?

Description is thorough and contains no fluff, but its length (multiple paragraphs) may hinder quick scanning. However, information is well-organized with distinct sections for modes, filters, and fill check.

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 complex logic and lack of output schema, the description fully explains the expected output format (opportunities[] with fields, partition_check details), edge cases (placeholder filtering, Jaccard similarity), and integration with sibling tools. No missing critical 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 descriptions for both parameters are comprehensive, but the description adds further value by explaining input formats (slugs, URLs vs seed questions), recommended usage, and the underlying logic each mode triggers. Examples provided enhance 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?

Description clearly states 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', specifies two modes (event and topic), and provides concrete examples. It differentiates from sibling tools by detailing unique methodology.

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 requirement for exactly one of `event` or `topic`, recommends when to use each, and warns against calling with no args. Also references `polymarket_fill_risk` for custom sizing, providing alternative 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?

The description goes far beyond annotations, detailing how edges are computed (slippage, Kelly fractions, model families), the response structure (by_segment, fed_candidates, _diagnostics), caching (1h at KV level keyed on knobs), and the 24h-move warning. Annotations only declare readonly and idempotent; the description adds rich behavioral context including filtering logic and data sources.

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

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

The description is front-loaded with the core purpose but then delves into extensive detail on model families, which makes it quite long. The use of all-caps section headers improves structure, but the length could be trimmed. Given the complexity, the length is somewhat justified, yet it remains less concise than ideal.

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

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

The description is exceptionally complete given the tool's complexity and the absence of an output schema. It explains the response structure (by_segment with three segments, fed_candidates, _diagnostics), the edge calculation, filtering logic, caching, and even notes about Fed bets being excluded. This leaves little ambiguity about what the tool returns and how to interpret results.

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

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

Schema coverage is 100% with descriptive comments for each parameter (e.g., min_liquidity explains set to 5000 to drop thin-book). The description adds a 'TRADEABLE-EDGE KNOBS' section reiterating purposes but does not introduce new parameter semantics beyond the schema. The baseline is 3, and the description does not elevate above that.

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 scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with the explicit use case 'what should I bet on today'. It specifies it discovers opportunities without paging through hundreds of markets, distinguishing it from a generic market list. Sibling tools like polymarket_arbitrage suggest they focus on arbitrage, so edges stands out as a broader opportunity finder.

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: use this tool for discovering betting opportunities on Polymarket, built for daily discovery. It implies agents should use it as a starting point. However, it does not explicitly state when to avoid it or compare with siblings like polymarket_arbitrage, omitting exclusions. Still, the context is strong enough for most agents.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds rich behavioral context: snapshots written only on cache-miss, decay based on daily closes of edge_pp_net, not intraday. It explains the response structure and computed fields like trend and decay_pp_per_day. 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 densely packed with useful information, well-structured with purpose first, then response details, then limitations. Each sentence adds value, though it could be slightly more succinct. Still, it is clear and organized.

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 comprehensively explains the response: tracked[], expired[], snapshot_dates[], with fields like first_seen, trend, decay_pp_per_day, lifespan_days. It covers limitations (60-day TTL, snapshot start, not intraday). This is 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%, so baseline is 3. The description mentions parameters (days default 14 max 30, window default '1wk') but adds no new semantic meaning beyond the schema's descriptions. The schema already defines defaults and ranges.

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

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

The description clearly states the tool provides 'Edge persistence and decay telemetry' from daily snapshots, answering a specific question about edge longevity. It distinguishes itself from sibling tool 'polymarket_edges' (which likely provides current snapshots) by focusing on time-series analysis.

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

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

The description includes use context via the example comparing fresh vs. old edges, implying when to use. It mentions limitations like 60-day TTL and snapshot gaps. It could be more explicit about when NOT to use (e.g., for intraday data) but is clear enough.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. Description adds rich behavioral context: walks the ladder, returns detailed fill metrics, verdict, per-leg info, and risk of forced directional exposure. No contradiction with annotations.

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

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

Description is long but well-structured with clear sections and uppercase keywords. Every sentence is informative, but minor redundancy in explaining return fields that could be slightly more compact. Still highly efficient.

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

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

Given no output schema, description fully covers both modes' return values, modes of failure, and risk implications. Explains the dominant loss mode in arb bots. 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%. Description adds meaning beyond schema: clarifies side defaults for basket, size_usd interpretation for each mode, and explains market vs event parameter roles. Adds clamps and default values.

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

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

Description clearly states it checks realizable vs theoretical edge against live order-book depth. It explicitly distinguishes two modes (single-market and basket) and names sibling tools (polymarket_arbitrage, polymarket_edges) as tools to use before acting on their signals.

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 REQUIRES one of market or event, provides detailed instructions for each mode, and states precisely when to use this tool: before acting on arbitrage signals or trades above ~$500. Also warns about partial basket fills converting arb into unhedged directional positions.

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

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

The description adds substantial behavioral context beyond annotations: it details compatibility_warning conditions, temporal alignment, skipped cross types, and that real spreads are rare. Annotations already indicate read-only and idempotent behavior, and the description enriches this with specific edge cases and response fields. 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 thorough and well-structured with clear sections (MODES, RESPONSE, SAFETY FIELDS). While slightly verbose with nested explanations, every sentence adds value for a complex tool. Front-loading the main purpose is effective.

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

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

For a complex tool with no output schema, the description is remarkably complete. It covers all modes, response format, safety fields, temporal alignment, and conditionals. The agent can understand behavior, inputs, outputs, and limitations without additional context.

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

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

Schema coverage is 100% for three parameters, and the description adds significant meaning: it lists all topic values, explains that kalshi_event_ticker and polymarket_event_slug override topic-mapped sides, and provides examples. This enriches the schema beyond its minimal descriptions.

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

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

The description clearly states the tool's purpose: comparing cross-venue spreads between Kalshi and Polymarket. It specifies two modes (topic and explicit) and distinguishes it from siblings like polymarket_arbitrage. Use of specific verb 'Cross-venue spread' and resource identification makes it highly clear.

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

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

The description provides explicit guidance on when to use each mode: topic for pre-mapped macros and explicit tickers for custom pairings. It also warns that most pre-mapped topics yield compatibility warnings, helping agents decide against misuse. However, it lacks explicit 'when not to use' statements, e.g., if only one venue is needed.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by explaining scoping and the listing behavior when key is omitted. 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, front-loaded with key verb and resource, no filler. Each 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?

For a simple retrieval tool with one optional parameter and no output schema, the description fully covers behavior, usage, and scoping. No gaps.

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

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

Schema coverage is 100% and the parameter description in schema already covers omitting key to list all. The description reinforces this but does not add new syntax or format details 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 retrieves a value saved via remember or lists all keys if no argument is provided. It explicitly distinguishes from sibling tools remember and forget.

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

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

The description explains when to use the tool: to look up previously stored context without re-deriving. It also notes scoping and pairing with remember/forget. Absent explicit when-not cases, but context implies exclusive use for retrieval.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds important behavioral context, such as the side effect of mark_read (flagging events as read) and that polls work fine. 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, well-structured paragraph that front-loads the purpose, then provides details on returned fields, filtering, and usage. Every sentence adds meaningful information, 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?

For a tool with 5 parameters and no output schema, the description adequately explains what is returned (source, citation_uri, raw payload) and provides usage context (polling, alternative access via URL). It covers all necessary aspects for an AI agent to use it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the filtering purpose of type and since, and the behavior of mark_read and unread_only, which goes beyond the schema descriptions. It also gives an example for type.

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 action: 'Pull fired events from your subscription feed.' It specifies what is returned (most recent alerts with source, citation_uri, and raw payload) and mentions filtering options. It distinguishes itself from sibling tools by focusing specifically on the alert feed.

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

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

Provides explicit usage guidance: filtering by type (e.g., 'sec_8k') and ISO timestamp, use of mark_read, and suitability for polling. It also mentions an alternative access via a registry URL for scripts/dashboards. While it doesn't explicitly list when not to use it, the context is clear enough.

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

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

Annotations already declare idempotent, read-only, non-destructive. Description adds details on multi-source fan-out, fallback logic, API sunset status, and return structure. No contradictions.

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

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

Description is detailed but front-loaded with example queries. Every sentence adds value, though could be slightly more concise. Still well-structured.

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

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

Given no output schema and complex behavior, description covers sources, fallback, parameter details, return format, and when to use alternative tool. Highly complete.

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

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

Schema coverage is 100%, and description explains each parameter beyond schema: 'since' format with examples, 'value' as ticker or CIK, 'type' limited to 'company'. Adds practical usage tips.

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

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

The description clearly states the tool provides a change feed for a company in a given time window, listing specific sources and distinguishing from sibling tool entity_profile. It includes example queries that match typical user intent.

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

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

Explicitly tells when to use (e.g., 'What's new with X') and when not to (use entity_profile for static profile). Provides fallback behavior (GDELT→GNews) and parameter guidance ('30d' for typical monitoring).

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=false and destructiveHint=false, and the description adds key behavioral context: scoped storage, persistence differences between authenticated and anonymous users (24 hours for anonymous), and pairing with recall/forget. No contradictions.

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

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

Four sentences, front-loaded with the core purpose, then usage guidance, then storage details, then pairing. No fluff.

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

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

Given two simple string parameters with full schema coverage and no output schema, the description covers all necessary context: purpose, when to use, storage behavior, and pairing.

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

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

Schema coverage is 100% with clear descriptions. The description adds some extra context about value types (findings, addresses, etc.) but doesn't significantly extend the schema.

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

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

The description uses a specific verb-resource pair ('Save data the agent will need to reuse later') and provides concrete examples (ticker, address, preference). It clearly distinguishes the tool from siblings like 'recall' and 'forget'.

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

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

The description explicitly states when to use this tool ('when you discover something worth carrying forward') and identifies alternatives ('Pair with recall to retrieve later, forget to delete').

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by explaining internal cascading lookups and specifying return fields for each type, including citation URIs. No contradiction with annotations.

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

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

The description is front-loaded with examples and purpose. While it is relatively long, every sentence serves a purpose—defining usage, explaining return data, and noting internal behavior. Could be slightly more concise but is well-structured.

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

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

Given the simple input schema (2 params, no nested objects) and lack of output schema, the description fully compensates by detailing return values, citation URIs, and supported entity types. It thoroughly covers what the agent needs to use 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?

Schema coverage is 100%, so baseline is 3. The description adds meaning by clarifying acceptable input formats for 'value' (ticker, CIK, name for company; brand/generic for drug) and what the 'type' enum implies, thus exceeding the baseline.

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

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

The description starts with concrete examples like 'What's the ticker for…' and clearly states the tool maps user-spoken names to canonical/official identifiers. It distinguishes itself from sibling tools that likely require these IDs as input, making its purpose unambiguous.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear context for when to invoke. It also details supported types and their inputs. Lacks explicit 'when not to use' but the guidance is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that it probes each entity, returns score/confidence/signal density, and requires an API key for certain models. 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?

Two sentences plus a usage example, front-loaded with the core action, 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?

Describes return fields (ranked list with score, confidence, signal density) and constraints (2-8 entities). No output schema, but enough context for effective use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that the first entity is the 'subject' and rest are competitors, and provides context for optional 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 it compares AI visibility across multiple entities side-by-side, probing with ai_visibility_check and returning a ranked list. It distinguishes itself from single-entity tools like ai_visibility_check.

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

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

The description provides a clear use case (competitive AI-marketing audits) and an example question. However, it does not explicitly state when not to use it or mention alternative tools like ai_visibility_check for single entities.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds important behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will be listed if it times out. 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 well-structured, starting with a clear purpose and then covering sources, use cases, return values, limitations, and error handling. Although somewhat long, every sentence adds value, and it is front-loaded with the primary 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?

Given the complexity of a composite check across multiple sources, the description fully covers what the tool does, what it returns, version fallback, ecosystem scoping, and graceful degradation. No output schema exists, but the description adequately explains the return structure.

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

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

Schema description coverage is 100% (both parameters documented). The description adds context by explaining the default behavior for version ('defaults to the latest published version when omitted') and how the parameters are used in the composite check, which goes beyond the schema.

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

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

The description clearly states the composite check for npm packages across deps.dev and bundlephobia, explicitly listing what it evaluates (license, advisories, bundle size, etc.) and distinguishes from sibling tools by specifying that other ecosystems are covered by a separate tool (deps.dev:version).

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 ('is X safe / popular / small', 'what does adding lodash cost me') and ecosystem scope ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), guiding the agent on when to use this tool and when to use alternatives.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the tool returns a quantum superposition answer and supports cat mode, which goes beyond annotations. It does not contradict annotations.

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

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

The description is brief (two sentences), front-loaded with the main purpose, and includes only essential information without redundancy.

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

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

Given the existence of an output schema and full parameter descriptions, the description provides sufficient context. It explains the core behavior and special modes, though it could briefly mention that observing collapses the wave function.

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

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

All 5 parameters are fully described in the input schema (100% coverage). The description adds minimal extra meaning beyond the schema, except contextualizing 'cat mode' for the cat 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's purpose: ask a yes/no question and receive a quantum superposition answer. It also mentions 'cat mode' for absurdist responses, which is unique among siblings, providing clear differentiation.

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 does not explicitly state when to use this tool versus alternatives like deep_research or ask_pipeworx. While the purpose is clear, guidance on when to choose this over other query tools is absent.

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

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

Adds significant context beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, character offset verification, 200K char limit with truncation flag. No contradiction with annotations.

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

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

Single paragraph, dense with information, each sentence adds value. Could be slightly more concise but efficiently communicates all necessary details.

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

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

No output schema, but description fully explains output (top-N passages with offsets and scores), covers key behavioral constraints (embeddings, windowing, truncation), and links to sibling tool for grounded use. Entirely adequate.

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

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

Schema coverage is 100%, so parameters are already documented. Description reinforces semantics (e.g., text is document text, query is natural-language) but does not add substantial new details beyond schema.

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

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

Clearly states it does semantic search inside a fetched record, with examples (SEC 10-K, article). Distinguishes from sibling tools by naming ask_pipeworx_grounded and describing the pairing.

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

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

Explicitly says when to use: 'when the record is too big to cram into the prompt.' Provides alternative and best practice: 'fetch with the gateway, ground over the relevant passages instead of the whole document.'

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 behavioral traits beyond annotations: it's a mutation (create), requires authentication, mentions SMS cap (10/day), webhook auto-disable after 10 failures, and delivery channel details. No contradiction with annotations.

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

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

The description is detailed but well-structured with bullet points for types and delivery channels. It is front-loaded with the main purpose. Slightly verbose but still efficient.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description covers types, params, delivery channels, constraints (SMS cap, webhook secret), and prerequisites (account). It is comprehensive.

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

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

With 100% schema coverage, the description adds detailed examples and constraints for each parameter (e.g., type-specific params, delivery channel options). It enriches the schema with practical usage context.

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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

It specifies when to use (proactive monitoring), requires a Pipeworx OAuth account, and lists supported subscription types with examples. However, it doesn't explicitly state when not to use or mention alternatives beyond the sibling tool list.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds rich behavioral context: returns examples from live catalog, can be focused by topic, and is the onboarding entry point. Slightly redundant with annotations but adds value.

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

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

The description is comprehensive but slightly long. It front-loads common user queries and then details usage. Every sentence adds value, but could be trimmed slightly without loss.

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 high schema coverage, comprehensive annotations, and no output schema, the description fully covers everything needed: what it returns (category-bucketed), how to call it, when to use, and parameter details. No gaps.

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

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

Schema coverage is 100% with a single 'topic' parameter. The description adds concrete valid values (finance, pharma, etc.) and explains the behavior when omitted (full spread), going beyond the schema description.

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

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

The description clearly states the tool returns category-bucketed example questions for onboarding. It explicitly lists categories and positions itself as the entry point for new users, distinguishing it from siblings like ask_pipeworx or discover_tools.

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

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

Explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to omit or pass a topic. Also mentions learning how to call meta-tools, providing clear context.

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

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

The description adds context beyond annotations by clarifying that the row is deactivated (not deleted) and historical events remain available via 'recent_alerts'. Annotations already indicate non-destructive and idempotent behavior, but description reinforces the actual 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 sentences, no wasted words. Each sentence provides distinct value: action, ownership, and effect.

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 one-parameter tool with no output schema, the description fully covers purpose, constraints, and side effects. It also references sibling tool 'recent_alerts' for historical data, providing complete 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% with a well-described 'id' parameter. The description does not add significant new information beyond stating 'by id'. Baseline score of 3 is appropriate.

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

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

The description clearly states the action 'Cancel a subscription by id' and distinguishes from siblings like 'subscribe' by focusing on cancellation. Ownership enforcement adds specific context.

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 indicates when to use this tool (to cancel a subscription) and mentions ownership constraint. However, it does not explicitly state when not to use it or mention alternatives like 'list_subscriptions' for viewing active subscriptions.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. Description adds that it returns a verdict with categories, structured form, actual value with citation, and percent delta. It also discloses the verification process and source (SEC EDGAR + XBRL). No contradictions with annotations.

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

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

Description is moderately long but well-structured: starts with natural language triggers, then states purpose, usage, scope, output format, and efficiency claim. Every sentence adds value. Slightly lengthy but 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?

With no output schema, the description fully explains the return value (verdict categories, structured form, actual value with citation, percent delta). It also provides context on efficiency by replacing sequential calls. Missing error handling or ambiguous case details, but sufficient for most use cases.

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

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

Schema description coverage is 100%, and the schema description for the single parameter is detailed with examples. The overall description adds context about claim processing but doesn't significantly enhance parameter semantics beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides explicit triggers like 'Is it true that…' and specifies the domain (company-financial claims via SEC EDGAR + XBRL). This differentiates it from siblings by noting it replaces multiple sequential calls.

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

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

Description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also notes the domain limitation (v1 supports company-financial claims), giving clear context. Missing explicit 'do not use' for non-financial claims, but the limitation is clear.

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