Emoji Oracle

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds key behaviors: default free model, BYO Anthropic key with direct payment, per-model response structure.

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

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

Concise, single paragraph with clear front-loading of purpose, followed by detail and use cases. Every sentence adds value, 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?

Comprehensively covers inputs, optional parameters, and return format (per-model scores, confidence, signals, raw_response, combined view). Lacks output schema but description suffices.

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

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

Schema coverage is 100%, but description adds meaning beyond schema: explains default model, purpose of _apiKey (BYO key, direct payment), and context disambiguation role.

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

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

The description uses specific verbs (probe, score) and resources (LLMs, visibility) and clearly distinguishes from siblings like ask_pipeworx or bet_research by focusing on AI visibility scoring.

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 mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). Does not explicitly state when not to use or alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds key context: routing logic (to the right of 5,564 tools), citation format (pipeworx://), and that it works on every tier in one fast call. 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 comprehensive but slightly long at 4 sentences. The critical 'PREFER OVER WEB SEARCH' is front-loaded, which is good. Every sentence adds distinct value, but it could be tightened by removing the repetitive 'for most questions' endorsement at the end.

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 (6 params, no output schema, many sibling tools), the description covers purpose, alternatives, query patterns, sources, and behavior. No output schema means the agent has enough context to use it effectively.

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

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

Schema coverage is 100% with good descriptions for each alias. The description adds value by showing example questions and clarifying acceptable natural language input. Could gain a point by mentioning that the tool fills arguments automatically (already implicit in 'routes... fills arguments').

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 strong verb ('questions about...') and identifies a broad, specific resource ('5,564 tools across 1462 verified sources'). It clearly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by stating what to use each for.

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 the agent to prefer this over web search for many question types, and provides clear 'when to step up' guidance to two sibling tools. Also gives example query patterns ('what is', 'look up') that trigger this tool.

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

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

Annotations already convey readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by explaining the fallback behavior ('falls back to nothing — this IS a full working router'), the experimental nature, and the current equivalence to the stable router. It does not contradict annotations. Score 4 because it goes beyond annotations without being exhaustive about all edge cases.

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 a clear first sentence defining purpose and beta nature. It is front-loaded and each sentence adds value. Could omit minor phrasing like 'outcome evidence 2026-07-26' for brevity, but overall efficient.

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

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

Given the tool's complexity (5,564 tools, universal router), the description adequately covers its purpose, current status, and usage context. There is no output schema, but the description notes the response shape is identical to ask_pipeworx, which suffices. Some might want fallback behavior details, but the description already clarifies it's a full router.

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 baseline is 3. The description adds no further parameter details beyond stating identical arguments to ask_pipeworx. Since the schema already documents all six parameters (with aliases), the description doesn't need to elaborate. 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 explicitly identifies 'ask_pipeworx_beta' as a beta version of 'ask_pipeworx', a universal router with 5,564 tools. It clarifies that it has the same arguments and response shape, and contrasts it with the stable version by noting candidate routing improvements are tested here. This specificity and differentiation from siblings like 'ask_pipeworx' and 'ask_pipeworx_grounded' earns a top score.

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

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

The description provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It explains the current state (no candidate active, matches stable router) and how results are compared for merges. This directly tells the agent when to choose this tool over the stable version, earning full marks.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds critical behavioral context beyond annotations: the extra LLM call cost, the structured response format including refusal reasons, and the explicit constraint that answers come only from tool results. It does not mention authentication or rate limits, but those are likely system-wide. The added context is valuable and consistent.

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

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

The description is front-loaded with the core purpose and use case, followed by process details and usage conditions. It is slightly longer than necessary due to repeating the routing process already implied by the sibling tool, but every sentence adds value and the structure is logical. Could trim a few words without losing clarity.

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

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

Despite the absence of an output schema, the description fully documents the return structure on success (answer, evidence, confidence, source, fetched_at, refusal_reason) and explicitly lists possible refusal reasons. It also explains the tool routing and extraction logic. This provides a complete picture for the agent to understand behavior and handle failures.

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 each parameter (including aliases) documented. The description repeats that the input is a natural language question but adds no new constraints or formatting details beyond the schema. Per guidelines, the baseline is 3 when coverage is high, and the description does not compensate with additional semantic value.

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

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

The description explicitly states the tool's purpose as 'Hallucination-resistant answer mode for high-stakes reads' and details the process: it routes through the same pipeline as ask_pipeworx, selects a tool from 5,564 options, fills arguments, fetches data, then extracts an answer using only the tool result. This clearly distinguishes it from siblings by highlighting the grounded extraction step and the focus on preventing invention.

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

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

The description provides explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on' in high-stakes contexts like financial verdicts, legal claims, etc. It directly states when to prefer the alternative ('prefer ask_pipeworx for casual lookups') and explains the cost trade-off ('Costs one extra LLM call vs ask_pipeworx'). This is model usage advice.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds extensive behavioral details: market resolution, classification, parallel fan-out, return structure, edge cases (low confidence, closed, illiquid), resolution-rule risk, and parent event extraction. 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 a clear purpose statement. The description is lengthy but necessary given the tool's complexity and lack of output schema. Each section (response shapes, resolver contract, safety) earns its place. Could be slightly trimmed but is well-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?

With no output schema, the description fully documents the return structure (market, analysis, evidence, match confidence, parent event, news fields) and all edge cases (low confidence, closed markets, illiquid spreads, cancellation rules). Adequate for an AI agent 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% with clear parameter descriptions. The description enriches this by explaining how the 'market' parameter is resolved (via slug, URL, or question text), how 'depth' affects fan-out, and that 'include_raw' controls summary vs full payload. 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?

Begins with a clear verb+resource statement ('Research a Polymarket bet') and specifies input types (slug, URL, question). The examples and sibling context show it is specialized for Polymarket betting, distinguishing it from other Pipeworx 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 says 'Use for...' with three common betting queries. Describes when the tool short-circuits (low confidence, closed markets) and when to inspect fields (market_match_confidence). Lacks explicit 'do not use' scenarios but provides ample context.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive. The description adds key behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), off-calendar fiscal year handling, sorted results, and citation URIs. No contradiction.

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

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

The description is front-loaded with common queries and is concise at 4-5 sentences. It efficiently conveys purpose, usage, and behavior 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 no output schema, the description explains return format (paired data + citation URIs) and sorting behavior. It covers the tool's key aspects 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%. The description adds context for values (tickers/CIKs for company, names for drug) and explains what data each type retrieves, enhancing the schema's 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 it performs side-by-side comparison of 2-5 companies or drugs in one parallel call, listing common query phrases (e.g., 'which is bigger') and distinguishing from sibling tools like entity_profile.

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

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

The description explicitly says to prefer this over sequential single-pack lookups and explains when to use company vs drug type. It lacks explicit exclusions but provides 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?

The description extensively covers behavioral traits: it's a read-only, idempotent operation (consistent with annotations), describes the parallel decomposition approach, explains gap reporting with explicit gaps[], mentions hop field and citation_uris with fetchability guarantees, discusses semantic excerpting behavior for large records, and provides realistic latency expectations. The description adds substantial context beyond what annotations provide, such as the account requirement, the nature of the data sources, and the gap recovery mechanics. No contradiction with annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false all align with the research behavior described).

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

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

The description is long but packed with essential information, and it front-loads the critical usage constraints (account requirement, alternative for unauthenticated users). Each sentence adds substantive detail. It could be slightly more structured (e.g., bullet points for related guidance), but the density of high-value information is appropriate for the tool's complexity. No fluff.

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

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

Given the tool's high complexity (2 params, no output schema, but sophisticated behavior), the description is remarkably complete. It explains the research process (parallel decomposition), expected output (findings packet with evidence, confidence, source, timestamps, citations, gaps, contradictions), constraints (account, paid tier for thorough), latency, iteration behavior per depth level, and fallback for unsupported topics. Without an output schema, the description adequately describes the return format. Consideration of all signals is evident.

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 only 2 parameters, so the baseline is 3. The description does add some semantic value: it explains the depth levels in more detail than the schema (e.g., 'standard=3 (default; adds a gap-recovery hop)'), and clarifies that the question parameter accepts broad/multi-part natural language. However, it doesn't add a huge amount beyond what the schema already provides—the schema's descriptions are already fairly detailed. The description's main value is in the overall tool context rather than per-parameter specifics.

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: it does grounded multi-source research across 1462 structured data sources using parallel decomposition across 5,564 tools. It distinguishes itself from siblings like ask_pipeworx, which is for single lookups, and explicitly explains what kind of questions it's best for (broad/multi-part) and what alternatives handle better (breaking news).

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 vs alternatives, including specific scenarios for ask_pipeworx ('single lookup') and ask_pipeworx for breaking news. It also clearly states the account requirement, mentions the paid plan needed for 'thorough' depth, and gives concrete examples of good vs bad queries. It even covers second-hop iteration differences between depth levels. This is comprehensive usage 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 annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that results include 'full input schemas (with curated examples)' and that each result is 'ready to call directly.' It does not contradict annotations but adds useful context about the return format. No additional behavioral details (e.g., rate limits, pagination) are provided.

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 the main purpose, and structured logically: what it does, when to use, what it returns, and a call-to-action ('Call this FIRST'). Every sentence adds value with no redundancy.

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

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

Given the tool's complexity (meta-tool, 6 parameters, no output schema), the description provides sufficient context: purpose, usage scenario, return format (names, descriptions, schemas with examples). It could be enhanced by noting that discovery is limited to the tool provider's registry or by explaining the search mechanism, but it is largely complete 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?

With 100% schema description coverage, the schema already documents all parameters (including aliases and limit). The description adds value by providing natural language examples ('look up FDA drug approvals', 'analyze housing market trends') and clarifies that the query accepts natural language. However, the incremental meaning beyond the schema is modest.

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 specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself from siblings by noting it returns top-N ready-to-call tools. The phrase 'Call this FIRST when you have many tools' further clarifies its role as a discovery tool.

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

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

The description explicitly states when to use this tool: 'Use when you need to browse, search, look up, or discover what tools exist for...' and advises to 'Call this FIRST when you have many tools.' It implies that for specific known tasks, one might use sibling tools directly, but does not name alternatives or explicitly state when not to use it.

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

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

Annotations indicate a safe, idempotent, read-only operation. The description adds behavioral context by stating the output includes 'cryptic emoji prophecy', 'vibe rating (1-10)', and optional 'text explanation'. This goes beyond the annotations to describe the informal, amusing nature of the 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 two sentences, with the first sentence front-loading the purpose. Every word is meaningful; no fluff. It efficiently communicates what the tool does and what it returns.

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 covers the key outputs (emoji sequence, vibe rating, optional interpretation) and parameters. An output schema exists, so details on return format are not required. For a simple, playful tool this is complete. Minor omission: no error handling or edge cases, but acceptable for this 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%, so the description's addition is moderate. It reiterates the role of 'question' and adds context about 'interpret' (optional interpretation) and 'emoji_count' (number of emojis). It also mentions 'vibe rating' which is not in the schema. This adds value beyond the schema, justifying a 4.

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

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

The description clearly states the tool's purpose: asking a question to the Emoji Oracle and receiving a prophetic emoji response with a vibe rating. It specifies the verb 'Ask', resource 'Emoji Oracle', and outputs (emoji sequence, vibe rating, optional interpretation). This distinguishes it from sibling tools like 'ask_pipeworx' which are for different purposes.

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

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

The description explicitly says 'Ask the Emoji Oracle a question', which provides clear usage context for light-hearted, mystical queries. It does not provide explicit when-not-to-use or alternative tools, but the nature of the tool (cryptic emoji prophecy) naturally distinguishes it from more serious siblings like 'deep_research' or 'entity_profile'.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds detail: fans out across SEC, XBRL, USPTO, news, GLEIF; returns specific fields; notes patents API sunset soft-fail. 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 detailed but front-loaded with example queries. Every sentence serves a purpose. Slightly verbose, but still effective and well-structured.

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

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

No output schema exists, but the description fully covers return values: cik, company_name, recent_filings with URIs, fundamentals sorted, patents, news, LEI. Addresses limitations and future plans.

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

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

Schema coverage is 100% and the description adds context: type is only 'company' currently, value accepts ticker or CIK, names not supported. Enhances 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 specifies that the tool provides a holistic cross-source profile for US public companies, with example queries like 'Tell me about X' and 'company profile for Microsoft'. It clearly distinguishes from sibling tools like resolve_entity.

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

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

Explicitly states to prefer this over chaining individual lookups for holistic views, and advises using resolve_entity first if only a name is available. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true; description adds 'clear sensitive data' context but 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?

Two sentences with no waste; purpose and usage 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?

Description covers purpose, usage, and pairing with siblings; sufficient for a simple tool with full schema and annotations.

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

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

Schema coverage is 100%, so baseline is 3; description adds little beyond schema's description of 'key'.

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

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

Description states 'Delete a previously stored memory by key' clearly specifying verb and resource, and distinguishes itself from siblings 'remember' and 'recall' referenced in the description.

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 when to use: 'when context is stale, the task is done, or you want to clear sensitive data', and suggests pairing with related 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=true and idempotentHint=true. The description adds process details (fetch, extract, emit) and output format, but does not contradict annotations. Additional behavioral context beyond annotations is minimal.

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 few sentences, front-loaded with purpose, followed by details. No superfluous text. Could be slightly tighter but 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?

With no output schema, the description explains the output format. Both parameters are well covered. Annotations provide safety profile. Use cases are given. Complete for a simple read-only generation 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?

Input schema covers both parameters with descriptions. The description adds an example for 'url' and restates default for 'max_links', but provides no new semantic meaning beyond the schema.

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

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

The description clearly states it generates an llms.txt file, specifying the resource (site URL) and the action (fetch, extract, emit). It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on llms.txt generation.

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

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

Explicit use cases are given (client indexing, own project, competitor audit), but no direct when-not-to-use or alternatives compared to siblings. The context is clear but lacks exclusion criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds that it returns specific fields and is scoped to the caller's subscriptions, providing useful behavioral context beyond annotations.

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

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

Two concise sentences: first states purpose and output, second provides usage guidance. No extraneous information.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers purpose, return fields, and usage context comprehensively. Annotations handle safety profile.

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 single parameter (include_inactive) is fully described in the schema (100% coverage). The description does not add additional meaning, so baseline score applies.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields. It distinguishes from siblings like subscribe/unsubscribe by framing it as a lookup tool for review and cancellation.

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

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

The description explicitly advises when to use: 'review what you're monitoring before adding more or to find an id to cancel.' This gives clear context and implies alternatives (subscribe/unsubscribe).

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 are all false and thus provide little behavioral insight. The description compensates by disclosing rate limits ('5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and the claim_token workflow for anonymous filing and later retrieval. This adds significant 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 is front-loaded with a clear purpose and then delivers dense, non-redundant guidance. Every sentence earns its place—usage triggers, exclusions, token mechanics, rate limit, and cost. Despite its length, no word is wasted.

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

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

Even though there is no output schema, the description explains the key return behavior: 'Filing without an account returns a claim_token' and how to later use it to read the fix status and changes. It also covers rate limiting, quota, content guidance, and exclusion rules, making it fully complete for a feedback 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 schema already describes all parameters (100% coverage), so baseline is 3. The description adds extra meaning for the message parameter ('describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and operational semantics for claim_token (how to use the returned token to read status), elevating it above 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 opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly distinguishes the tool from siblings like ask_pipeworx or discover_tools, which are query/research tools, by focusing on sending feedback about the Pipeworx toolset itself.

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 conditions are given: '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).' It also provides a clear exclusion when the tool belongs to a different MCP server, directing users to file elsewhere, and advises on what to include ('describe in terms of Pipeworx tools/packs').

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds valuable context: self-aggregating, derived from CF analytics-engine, no PII, cached 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?

Description is concise and well-structured: first sentence states core functionality, then bullets use cases, then technical notes. Every sentence adds value without repetition.

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

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

Given annotations and rich schema, the description is complete. No output schema, but return values (top tools, packs, volume) are clearly implied. Caching behavior is useful additional detail.

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?

Only one parameter (window) with enum and description in schema. Description adds clarifying context about shorter vs longer windows, which provides additional meaning beyond the schema.

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

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

Description clearly states the tool returns top tools, top packs, and total call volume over recent windows. It distinguishes itself from sibling tools like discover_tools or ai_visibility_check by focusing on trending usage 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?

Explicitly lists three use cases: discovering hot data sources, confirming canonical tool, and checking alignment. Notes that shorter windows surface hotness while longer show steady-state demand. Could be improved by mentioning 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?

Discloses threshold (3pp), similarity filter (0.30 Jaccard), partition filter (placeholder >20%), fill check behavior, and realizable edge condition. Annotations already declare read-only, idempotent, non-destructive, so no contradiction.

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

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

Front-loaded with purpose and modes, but the lengthy detail (Jaccard threshold, partition filter, fill check) could be slightly trimmed without losing value. Still, every sentence contributes.

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

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

No output schema, but description explains response fields (opportunities[], partition_check, fill_check) and edge cases thoroughly.

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

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

Schema covers both parameters with basic descriptions; the tool's description adds rich context: examples, internal mechanics, and use-case recommendations, far exceeding the schema.

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

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

Clearly states it finds arbitrage on Polymarket via monotonicity violations and partition-sum checks. Differentiates from sibling tools like polymarket_fill_risk.

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

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

Explicitly tells when to use each mode (event vs. topic), when to call with no args for trending scan, and directs to polymarket_fill_risk for custom sizing.

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

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

Beyond annotations (readOnlyHint, etc.), the description details caching (1h), computation logic for each model family, response structure, edge cases like Fed bets, and effect of knobs. 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 very detailed but excessively long for an AI agent. While well-structured with sections, it could be more concise by summarizing core behavior and deferring details to schema.

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 params, multiple segments, diagnostics), the description covers return values, caching, and empty-segment diagnostics comprehensively. No output schema, so description compensates 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?

All 9 parameters have descriptions in the schema (100% coverage), and the description adds extra context like default values, meaningful explanations (e.g., partition arbs always return kelly_fraction_half=0), and 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 scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It distinguishes itself from siblings like polymarket_arbitrage by focusing on disagreement-based edges and providing a specific use case.

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

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

The description gives strong usage guidance with 'what should I bet on today' and explains when to use different segments. It notes when not to rely on certain signals (e.g., Fed bets) but does not directly compare to 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 indicate safe, read-only behavior. The description adds significant behavioral detail: response structure (tracked, expired, snapshot_dates), field semantics (trend classification, decay calculation from daily closes), and data source constraints. No contradictions with annotations.

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

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

The description is well-structured with front-loaded purpose, clear response format explanation, and a limitations section. It is fairly dense but every sentence adds value; could be slightly more concise without losing clarity.

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

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

Despite lacking an output schema, the description thoroughly documents all response fields (tracked with time-series, trend, decay; expired with lifespan_days; snapshot_dates) and explains data caveats (TTL, snapshot gaps, decay method). The agent has sufficient information to use and interpret 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% and the description largely repeats schema info (defaults, ranges, allowed values). It adds minimal extra meaning beyond what the schema already provides, meeting the baseline but not exceeding it.

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: telemetry on edge persistence and decay using daily snapshots. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical trend analysis, not just current edges.

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

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

The description explains when to use the tool (to check edge age and decay) and provides context on data limitations (60-day TTL, snapshot gaps). It implicitly guides the agent away from using it for real-time edge data, but does not explicitly list alternatives or 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?

Beyond annotations (readOnly, idempotent, etc.), the description explains that the tool walks the CLOB ladder, calculates fills, and returns verdicts like 'clean/degraded/cannot_fill'. It details basket mode risks, such as stranded directional positions, which adds significant behavioral 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 front-loaded with a summary sentence and then expands into details. While lengthy, each sentence serves a purpose—explaining modes, parameters, return fields, and usage warnings. No redundancy, but could be slightly more compact for very rapid scanning.

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

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

Given the tool's complexity (two modes, no output schema), the description thoroughly lists return fields (top_of_book, vwap_fill_price, slippage_pp, capture_ratio, profit_usd, thin_legs, etc.) and explains the verdict system. It completely covers the expected outputs and edge-case behaviors.

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

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

Schema coverage is 100%, but the description adds value by explaining parameter interactions (e.g., side default differs by mode, size_usd interpretation varies). It clarifies the dual use of market/event parameters and the auto-detection for basket side.

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

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

The description clearly states the tool checks 'realizable-vs-theoretical edge' against live order book depth. It distinguishes between two modes (single-market and basket/partition) and explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges, indicating it is a pre-trade verification tool.

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

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

The description explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It warns about risks of partial basket fills and unhedged directional positions, providing clear guidance on usage context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds critical behavioral details: compatibility_warning conditions, temporal_alignment checks, skipped cross-type/subtype counters, and the caveat that real spreads are rare. 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 long but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). It front-loads the core purpose but then goes into extensive detail. While every sentence adds value for a complex tool, it could be slightly more concise without losing essential information.

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

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

Despite no output schema, the description explains the response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). It covers edge cases and safety fields, making it complete for an AI agent to understand what to expect and how to interpret results.

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

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

Input schema covers 100% of parameters with descriptions. The description adds context: topic parameter lists all 10 shortcuts, explicit parameters override topic-mapped sides, and explains the relationship between parameters. This adds value beyond the schema, justifying a score above baseline 3.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like polymarket_arbitrage by specifying the cross-venue aspect. Verb 'spread' + resource 'polymarket_kalshi' makes purpose specific.

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 (topic shortcuts vs explicit tickers) and when each is appropriate. It warns that most pre-mapped topics return compatibility_warning, advising against blind use. However, it does not explicitly list when to use alternatives like polymarket_arbitrage, though it implies this tool is for cross-venue 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?

Annotations already provide safety hints. Description adds scoping detail (anonymous IP, BYO key hash, account ID), which is beyond annotations. No contradictions.

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

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

Three concise sentences front-loading purpose, then usage, then scope. 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 simple tool with one optional param and no output schema, the description covers purpose, usage, scoping, and sibling pairing completely.

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%. Description adds meaning: omitting key lists all keys, and gives concrete use-case examples (ticker, address, notes).

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

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

Clear verb+resource: 'Retrieve a value' or 'list all saved keys'. 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?

States when to use: look up stored context without re-deriving. No explicit exclusions, but context is clear.

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

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

Describes side effects of mark_read parameter (flagging events as read), which contradicts the readOnlyHint annotation. Adds critical behavioral context about state modification and that it is idempotent for read operations but not fully read-only.

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

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

Three sentences effectively cover main action, return fields, filtering, and an alternative access method. Could be slightly more structured (e.g., bullet points) but remains clear and efficient.

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

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

Despite no output schema, description explains return fields (source, citation_uri, raw payload) and covers all parameters including state management (mark_read/unread_only). Includes practical polling advice and alternative endpoint for scripts.

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?

Adds meaning beyond schema descriptions: explains type filters by subscription type, since as ISO timestamp, mark_read to avoid duplicates, unread_only for fresh events, and limit as max. Enhances understanding of each parameter's purpose.

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 pulls fired events from subscription feed, specifies return fields (source, citation_uri, raw payload), and mentions filtering by type and ISO timestamp. Distinguishes from sibling tools like 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?

Provides usage context: polls work fine and mentions alternative API endpoint for scripts/dashboards. Implicitly suggests when to use the direct API vs this tool, but does not explicitly list when not to use or compare to other similar 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 goes beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) by detailing the fan-out to multiple sources, fallback logic, USPTO patent note, and return structure (grouped changes, total count, 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 well-structured with query examples at the start and technical details following. Every sentence adds value, though it is somewhat lengthy. Slight room for conciseness but overall 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?

Given the tool's complexity (multiple data sources, fallback, parameter flexibility, and no output schema), the description is highly complete. It explains all sources, fallback logic, return format, and parameter usage. The explicit mention of return structure compensates for the lack of an 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 description coverage is 100%, so baseline is 3. The description adds value by explaining the 'since' parameter's dual format (ISO date and relative shorthand with examples), clarifying 'type' is limited to company, and specifying 'value' can be ticker or CIK. This extra context raises the score to 4.

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

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

The description clearly states the tool provides a change feed combining SEC filings, news, and patents for a company. It gives example queries like 'What's new with X' and distinguishes itself from the sibling tool 'entity_profile', which provides a static profile regardless of window.

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

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

The description explicitly says when to use this tool (for recent changes over a window) and when not to (use entity_profile for static profile). It provides guidance on the 'since' parameter format (ISO date or relative shorthand) and explains fallback behavior between GDELT and GNews.

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, idempotentHint=true, destructiveHint=false. The description adds valuable context beyond annotations: key-value scoping by identifier, persistence differences (authenticated vs anonymous), and the fact that it's a write operation. 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 three sentences, each serving a distinct purpose: purpose, usage guidance, behavioral context. Every sentence is informative, no fluff, and the most critical info 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?

Given that there is no output schema, the description adequately explains the storage mechanism, scoping, and retrieval pairing. Combined with rich annotations and clear parameter schema, the tool's behavior is fully specified for effective agent use.

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

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

Schema coverage is 100% with descriptions for both 'key' and 'value'. The description adds naming convention examples for keys and specifies that values can be any text, which slightly enhances meaning beyond the schema. A higher score would require more detailed format specifications.

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 'Save data the agent will need to reuse later' and clearly indicates the resource (key-value memory). It distinguishes from sibling tools 'recall' and 'forget', 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?

The description explicitly states when to use: 'when you discover something worth carrying forward' and provides examples. It also mentions pairing with 'recall' and 'forget' for completeness and gives storage scoping details, leaving no ambiguity about alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds substantial behavioral detail: internal cascading through multiple lookup endpoints, graceful degradation of LEI/FIGI enrichment, explicit labeling of unresolved identifiers, and source attribution for every identifier. This goes well beyond the structured annotations.

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

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

The description is long but well-structured: starts with query examples, then states the core rule, then details supported types. Every sentence adds useful information, though the density of nested parentheticals could be slightly trimmed without losing 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?

With no output schema, the description fully carries the burden of explaining expected results. It describes returned identifier types, source labeling, unresolved identifier handling, ownership information, and fallback behavior, making the tool's behavior sufficiently predictable 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?

Input schema has 100% coverage for both parameters, but the description dramatically enriches parameter meaning. It explains accepted input formats (ticker, CIK, ISIN, name), the ISIN-to-LEI resolution path for non-US issuers, and the difference between company and drug types with examples.

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

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

The description states the tool's specific function: resolving user-spoken names to canonical official identifiers required by other tools. It gives concrete query examples and lists supported entity types, making the purpose unmistakable and distinct from sibling tools like entity_profile or compare_entities.

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 instructs 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It lacks explicit when-not-to-use exclusions, but the context and examples sufficiently signal its intended role.

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 behavior: probes each entity, ranks by score, returns metrics (score, confidence, signal density). No contradictions.

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

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

Three sentences, front-loaded with purpose, no wasted words. Efficiently covers usage, mechanism, and output.

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

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

Despite no output schema, the description explains return structure (ranked list with score, confidence, signal density). Parameters are fully covered by schema. Context is complete for this level of 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 value by clarifying that the first entity is the 'subject' for narrative, beyond what schema's descriptions provide.

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 AI visibility across multiple entities, probes each with ai_visibility_check, and ranks them. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

Explicitly states use case: 'competitive AI-marketing audits' and provides an example question. Lacks explicit when-not-to-use or direct alternatives, but context hints at distinction from single-entity probe.

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 crucial behavioral details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list 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 informative but slightly lengthy. It is well-structured: front-loads purpose, then usage, then return summary, then limitations. Every sentence adds value, though some detail could be 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 no output schema, the description fully details the return structure: summary block with specific fields, per-advisory detail, links, and alternative versions. Parameter coverage is complete. The description leaves no ambiguity about 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 clear descriptions for both parameters. Description adds value by explaining the default behavior for version (latest) and accepting scoped packages (e.g., '@types/node'), 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 tool's purpose: a composite check for npm packages using deps.dev and bundlephobia, answering safety, popularity, and size questions. It distinguishes from siblings by noting it covers multiple checks in one call, while other tools like deps.dev:version handle other ecosystems.

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

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

Explicitly states when to use: when agent asks about safety, popularity, size, or cost of adding an npm package. Also specifies when not to use: only npm ecosystem in v1; other ecosystems (PyPI, Maven, etc.) fall under deps.dev:version directly.

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 significant behavioral detail: embedding model (BGE-base-en), window size (500-char overlapping), character cap (200K with truncation flag), and return format (passages with offsets and similarity scores). No contradictions.

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

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

The description is well-structured: opens with bolded core action, then usage guidance, technical details, and pairing. 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?

Despite lacking an output schema, the description explains what is returned (passages with offsets and scores), covers limits and truncation, and suggests a workflow with ask_pipeworx_grounded. Complete for an AI to use correctly.

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

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

Schema coverage is 100%, so description adds value beyond schema. It explains text as the document to search, provides query examples (e.g., 'supply-chain risk'), and notes the max chars and default limit. This adds practical 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 clearly states it performs semantic search inside a fetched record, with concrete examples (SEC 10-K body, article). It distinguishes itself from siblings like ask_pipeworx_grounded by noting it saves context and provides offsets for verification.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt'. Mentions alternative sibling ask_pipeworx_grounded. Provides clear context for choosing this tool over others.

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

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

Discloses non-obvious traits: account requirement, type-specific parameters, delivery channels with limitations (SMS cap, webhook auto-disable, signing). 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?

Well-structured, front-loaded with purpose, then details. Every sentence adds value, though slightly verbose with repeated examples. Could be tightened without losing clarity.

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

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

Given complexity (multiple types, nested params, delivery) and no output schema, description covers all critical aspects: input, behavior, constraints, and return value.

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

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

Schema coverage is 100%, so baseline is 3. Description adds significant value with concrete examples for each subscription type's params and delivery format, going 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?

States clearly 'Create a proactive monitoring subscription' and distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation. Returns subscription id.

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 prerequisites (Pipeworx OAuth account), supported types with examples, and delivery options. Lacks explicit contrast with alternative tools, but context is clear.

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

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

Annotations already signal readOnly, openWorld, idempotent, non-destructive. The description adds that the tool returns example questions and does not perform mutations, and indicates it can be called without arguments.

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 somewhat lengthy; however, each sentence adds value. It starts with example queries and then explains output and usage, making it easy to scan.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage, parameter behavior, and return value shape completely.

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 explains the topic field. The description's mention of valid topics ('finance', 'pharma', etc.) aligns with the schema but adds no new information beyond the schema's own 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 with tool and argument shapes, and positions it as the onboarding entry point. It distinguishes from siblings like ask_pipeworx and entity_profile.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also guides on argument usage: 'Call with no arguments for the full spread, or pass topic to focus'.

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?

Extra detail beyond annotations: row is deactivated, not deleted, preserving history via recent_alerts. No contradiction.

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

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

Two efficient sentences, essential info 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?

Covers purpose, constraint, behavior (deactivate), and historical context. Complete for tool complexity.

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

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

Schema covers param fully; description adds source ('returned by subscribe') for 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?

Clear action 'Cancel' and resource 'subscription by id'. Distinguishes from sibling 'subscribe' as its inverse.

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 ownership enforcement (only own subscriptions). Missing explicit when-not-to-use but strongly implied.

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

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

Annotations already declare read-only/idempotent/open-world, but the description adds substantial behavioral context: the two processing paths (structured vs grounded), the precise meaning of 'could_not_verify' as a failed check with no evidential value, the meaning of 'unsupported', and the inclusion of citations and reasoning. This goes far beyond the annotations and prevents misuse.

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

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

The description is long but dense with actionable information. The opening trigger phrases and 'Use whenever' are immediately useful, and the rest covers return types and error semantics. The closing note about replacing sequential calls is a minor efficiency hint, not padding. No part feels redundant.

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 enumerates all six verdicts and carefully explains the ambiguous ones (could_not_verify and unsupported). It covers both input parameters, routing logic, and output structure (verdict, value, citation, reasoning). This gives an agent all the context needed to invoke and interpret 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% (both parameters are described). The description adds extra context by explaining the percent-delta math for financial claims and the default tolerance cap of 5%, complementing the schema's description of tolerance_pct. It doesn't fully explain the 'claim' format beyond examples, but the schema already covers it well.

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 opens with natural-language trigger phrases and explicitly states 'natural-language claim verification against authoritative sources.' It clearly distinguishes between company-financial claims (via SEC EDGAR/XBRL) and other factual claims (grounded pipeline), and enumerates the verdict categories. This makes the tool's purpose unmistakable and sets it apart from siblings like deep_research or entity_profile.

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

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

The description says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides concrete triggers. It also gives a routing rule for claim types. However, it does not explicitly name alternative tools or state when *not* to use this tool, so it lacks the explicit exclusions needed for a 5.

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