Phoenix Number

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral details: default model (Workers AI Llama-3.3-70b free), cost implications of Anthropic probe (BYO key), and output structure (per-model {score, confidence, signals, raw_response} + combined view). 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 concise with four sentences. It front-loads the core action and progressively adds details about parameters, returns, and use cases. No unnecessary words or repetition.

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

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

Given 4 parameters and no output schema, the description sufficiently explains the output format (per-model object with score, confidence, signals, raw_response plus combined view) and use cases. It lacks details on scoring logic and 'signals' meaning, but overall adequate for an AI agent to decide and invoke.

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 meaning beyond schema: explains default model, purpose of _apiKey (only for Anthropic, passed through), and context parameter for disambiguation. Each parameter's role is clearly articulated.

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: probing LLMs for knowledge about an entity and scoring visibility. It specifies the verb 'probe', the resource 'LLMs', and the output 'score visibility (0-100)'. The tool is distinct from siblings by its specific function as a visibility check.

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

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

The description explicitly lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the _apiKey parameter (only for Anthropic probing). It does not explicitly exclude non-use scenarios but provides clear context for appropriate usage.

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

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

Beyond the read-only annotation, the description discloses that the tool routes to thousands of sources, automatically fills arguments, and returns citation URIs — useful behavioral context not present in the annotations. It does not cover failure modes or rate limits, but annotations already provide the safety profile.

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 every section serves a purpose: preference over web search, coverage area, examples, and comparison with sibling tools. It starts with a strong directive and is well-structured, though slightly verbose.

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

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

For a complex routing tool with no output schema, the description explains return format (structured + citations), covers major domains, and provides usage alternatives. It is complete enough for an agent to select and invoke the tool correctly.

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

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

The input schema fully describes the 'question' parameter and all aliases, so the parameter semantics are already self-explanatory. The description adds example questions but no additional parameter-specific information beyond what the schema provides.

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

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

The description clearly states this is a natural-language query router that answers factual questions across many domains by selecting from 5,358 tools, and provides concrete examples. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly commands preference over web search, gives typical query patterns, and explains when to escalate to ask_pipeworx_grounded or deep_research. This is clear when-to-use versus alternatives guidance.

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

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

The description goes well beyond the safe-read annotations by disclosing that this is an experimental edge with live candidate routing improvements, the current inactive status, and the fact that it falls back to nothing (i.e., it is a fully working router). This gives the agent a strong understanding of potential variability and current behavior.

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

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

The description is well-structured and front-loaded, beginning with 'Beta version of ask_pipeworx' and then efficiently covering identity, current state, usage, and caveats. Every sentence carries meaningful information about the experimental nature and relationship to the stable tool, with no wasted words.

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

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

Despite lacking an output schema, the description states the response shape is identical to ask_pipeworx, which is sufficient. It fully covers the tool's current state, purpose, usage condition, and experimental edge, leaving no critical gaps for an agent deciding whether to invoke it.

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

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

Input schema has 100% coverage with descriptions for all 6 parameters including aliases, so the description adds no unique parameter semantics. The phrase 'same arguments' reinforces the stable-router relationship but does not add new details beyond what the schema already provides.

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

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

The description clearly identifies this as a beta variant of ask_pipeworx with the same universal routing surface, explicitly stating it has the same 5,358 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx sibling by highlighting live candidate routing experiments, making the purpose and scope 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?

It explicitly says to use it 'exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. This gives clear context and names the primary alternative, but it does not explicitly discuss when-not-to-use or contrast with the grounded sibling variant.

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

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

Annotations declare readOnly/openWorld/idempotent/non-destructive, but the description goes far beyond: it explains the refusal mechanism with specific reasons (not_in_source, no_tool_match, etc.), the return structure including evidence as verbatim quote, and the cost implication (extra LLM call). No contradiction with annotations.

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

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

The description is dense but every sentence adds value: purpose, process, output schema, refusal reasons, usage context, and cost trade-off. It is front-loaded with the core purpose and structured from what→how→when. No filler or 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?

With no output schema, the description compensates by detailing the success return shape and failure modes. It covers the full decision context: high-stakes use cases, sibling differentiation, cost, and refusal handling. A complete description for an agent to invoke this tool confidently.

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%: all six properties are described as aliases for question. The description does not add parameter-specific semantics beyond the schema, but the baseline is 3 given the high coverage. It does imply that the `question` parameter is used for routing and grounding, which adds slight context.

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

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

The description opens with a specific purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes from the sibling ask_pipeworx by emphasizing grounded extraction and explicit refusals. The verb 'extracts the answer using ONLY what the tool result contains' is distinct and unambiguous.

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

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

Explicit usage guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It names the alternative ask_pipeworx and gives the trade-off ('Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups'). This fully answers when to use and when not to.

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

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

The description extensively discloses behavioral traits beyond annotations. It explains the resolver contract (market_match_confidence, alternatives, suggestions), low-confidence match short-circuit, closed market handling, wide-spread tradeability warnings, and resolution-rule risk. Annotations already indicate safe, read-only, idempotent behavior, and the description adds rich context without contradiction.

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

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

The description is thorough but lengthy. It is well-structured with sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.), which aids readability. However, some details could be condensed without losing clarity, and the overall length may overwhelm an agent. A more concise version would be ideal.

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

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

Given the tool's complexity (3 parameters, no output schema, many behavioral nuances), the description is exceptionally complete. It covers input formats, classification, fan-out logic, response structure, resolver contract, edge cases (closed markets, low confidence, wide spreads), resolution-rule risk, and safety. No additional context is needed.

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

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

Schema coverage is 100%, but the description adds meaningful context: for 'market' it clarifies acceptance of slug, URL, or question text; for 'depth' it explains quick vs thorough behavior; for 'include_raw' it describes payload size implications. This goes beyond the schema descriptions, though the extra detail is moderate.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly identifies the verb (research), resource (Polymarket bet), and scope (one call). It distinguishes itself from sibling tools like 'polymarket_edges' by focusing on a single bet with full fan-out data.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It gives clear context for when to use this tool. However, it does not explicitly state when NOT to use it or mention alternative tools, which would have elevated the score to 5.

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

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

The description adds significant behavioral context beyond annotations: explains data source (SEC EDGAR/XBRL for companies, FAERS for drugs), details on fiscal year handling (AAPL Sep, NVDA Jan), sorting by primary metric, and citation URI return. This fully informs the agent about side effects and behavior.

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

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

The description is detailed but well-structured, front-loading the purpose and usage guidance. Every sentence adds value, though it could be slightly more concise by removing some redundant examples.

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

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

Given the lack of an output schema, the description explains that it returns paired data and citation URIs. It covers entity types, input constraints (2-5), data sources, and sorting. A bit more detail on output structure would be helpful but is not required.

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

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

The schema covers 100% of parameters, and the description enriches them by explaining what 'type' values do ('company' pulls financials, 'drug' pulls adverse events) and what 'values' expects (tickers/CIKs vs drug names). It adds meaning beyond the schema's enum and description.

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

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

The description uses specific verbs like 'compare', 'rank', and 'head to head' to clearly state the tool's purpose. It explicitly names the resource (companies or drugs) and distinguishes it from siblings like entity_profile (single entity) and validate_claim.

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 'ALWAYS PREFER over sequential single-pack lookups' and provides concrete example queries. It clearly conveys when to use (comparison scenarios) but does not explicitly exclude cases where sequential lookups might be preferable.

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, openWorld, idempotent, non-destructive), the description discloses critical behaviors: account sign-in requirement, paid threshold for 'thorough', parallel decomposition across 5,358 tools, return packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[]), semantic excerpting instead of head-truncation, and expected latency. No contradictions with annotations.

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

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

The description is long (about 200 words) but front-loaded with the most critical operational constraints (account, alternatives, non-open-web). Every sentence contributes useful context for a complex tool, though there is some redundancy with the schema's depth explanations. The dense structure is appropriate for the tool's complexity.

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

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

With no output schema, the description compensates by fully explaining the returned findings packet (verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], hop, citation_uri). It also covers expected latency, limitations with current-news topics, and the behavior for different depth levels, making it complete for an agent to select and invoke the tool.

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

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

Schema coverage is 100% with detailed enum descriptions for depth, so baseline is 3. The description adds meaningful information beyond the schema by explaining that depth:'thorough' requires a paid plan, and elaborates on the second-hop behavior for standard/thorough and the implications for multi-step questions. This extra context elevates it above baseline.

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

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

The description uses a specific verb ('Grounded multi-source research') and names the exact resource ('Pipeworx's 1395 STRUCTURED data sources... in ONE call'). It clearly distinguishes itself from siblings by explicitly stating 'this is NOT open-web search' and contrasts with ask_pipeworx for single lookups and current-news topics.

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 when-to-use guidance ('Best for broad/multi-part questions over structured data') and when-not-to-use guidance ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). It also names an alternative (ask_pipeworx) and notes the account requirement as a gate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond annotations and fully discloses the tool's behavior.

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

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

The description is a single paragraph but well-organized: it begins with the core purpose, lists example domains, then explains what it returns and when to use it. Every sentence adds value, though it is slightly lengthy. It is front-loaded with the most critical information.

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

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

Given the tool's complexity (discovery with multiple parameters and rich output), the description fully covers what it returns (full schemas with examples, ready to call) and when to use it. No output schema exists, but the description sufficiently explains the output. It provides a complete and actionable understanding.

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 all six parameters including aliases described in the input schema. The description mentions aliases but does not add significant new meaning beyond the schema. With full coverage, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides a wide range of example domains (SEC filings, financials, FDA drugs, etc.) and specifies that it returns top-N relevant tools with names, descriptions, and full input schemas, distinguishing it from sibling tools that perform specific tasks.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It lists many use cases, providing clear context for when to use it. Although it doesn't explicitly state when not to use it, the guidance is sufficient given the tool's role as a discovery tool among many specialized siblings.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds behavioral context: fans out across sources, soft-fails for patents (USPTO sunset), fallback for news, and returns specific fields. No contradictions.

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

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

Description is front-loaded with example queries, then usage preference, then detailed behavior. It is comprehensive but efficient for its content, with no wasted sentences.

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

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

Given no output schema, the description explains return values (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and limitations (patents sunset, names not supported). Lacks error handling details, but sufficient for a holistic profile tool.

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

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

Schema coverage is 100%, so parameters are documented. The description adds meaning: type only 'company', value as ticker or CIK, names not supported. This goes beyond the schema enum and description strings.

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

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

The description clearly states it provides a full cross-source profile of a US public company, specifying sources like SEC EDGAR, XBRL, USPTO, news, GLEIF. It distinguishes from chaining single lookups and siblings like resolve_entity and 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?

Explicitly advises to prefer this tool over chaining single-pack lookups when a holistic view is needed. Also states input requirements (ticker or zero-padded CIK) and directs to use resolve_entity if only a name is available.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data, which is useful but not critical 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?

Three sentences, front-loaded with purpose, 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?

Simple tool with one parameter, annotations present, and description covers purpose, usage, and sibling context 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% with description for 'key' parameter. Description adds no additional meaning beyond the schema's 'Memory key to delete'.

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 'Delete' and resource 'previously stored memory by key'. Distinguishes from siblings 'remember' and 'recall' by specifying deletion.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Mentions pairing with remember and recall.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds that the tool fetches the page, extracts title/description/key links, and emits standard markdown. No contradictions. Provides enough behavioral context beyond annotations for safe agent invocation.

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

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

Single paragraph, front-loaded with action and output. Every sentence adds value: action, process, output format, use cases. No redundant language. Highly efficient.

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

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

Covers main aspects: input (url), process (fetch, extract), output (single text blob), use cases. No output schema but description clarifies return format. Lacks error handling or edge cases, but acceptable for straightforward tool with good 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% and both parameters have clear descriptions in the schema. The description does not add substantial new meaning beyond restating schema information (e.g., 'Full URL' for url, 'default 25, max 50' for max_links). Baseline meets minimum but does not enhance.

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?

Specific verb ('generate') + resource ('llms.txt file for any URL'). Clearly states what it does: fetches page, extracts metadata, emits standard format. Distinguishes from siblings like 'scan_competitor_ai_presence' by its focused output (llms.txt vs. general AI visibility analysis).

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

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

Explicitly lists three use cases: get a client's site indexed, draft for own project, audit competitor. Provides clear context for when to use, though no explicit 'when not to use' or alternative sibling names.

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, so the non-destructive nature is clear. The description adds value by listing specific return fields (id, type, params, created_at, etc.), offering transparency beyond annotations.

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

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

Two sentences with front-loaded purpose and return fields, followed by usage guidance. No wasted words.

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

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

Despite no output schema, the description explicitly lists all return fields. The single optional parameter is fully described in the schema. Annotations cover safety. Everything is complete for a simple list tool.

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

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

Schema coverage is 100% with one parameter (include_inactive) already fully described in the schema. The description does not add parameter context, but baseline is 3 given high coverage.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes itself from sibling tools like subscribe and unsubscribe by narrowing the action to listing.

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 'Use this to review what you're monitoring before adding more or to find an id to cancel,' providing clear when-to-use context and implicit 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?

The annotation 'idempotentHint: true' implies the same input yields the same output each call, but the description explicitly says the number is random, contradicting idempotency. This is a serious inconsistency that could cause incorrect agent behavior.

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

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

The description is two sentences with no wasted words. It is front-loaded and effectively communicates the tool's purpose despite the humorous tone.

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 absence of parameters and presence of annotations and output schema, the description is sufficiently complete for a simple tool. It explains the output and lack of inputs, though the contradiction reduces clarity.

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?

No parameters exist, and schema description coverage is 100%. The description adds no parameter information, which is acceptable since there are none. Baseline for 0 parameters is 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 returns the current temperature in Phoenix, Arizona, but then says it's presented as a random number. This introduces ambiguity but does not obscure the basic function. It distinguishes from siblings with its unique humorous tone.

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?

No guidance on when to use this tool vs alternatives. It only states 'No inputs required,' which is trivial. There is no mention of when not to use or comparisons with 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?

Beyond annotations (which are neutral), the description discloses key behavioral traits: rate limit (5 per identifier per day), free usage, no quota consumption, and that feedback is read daily and affects roadmap. 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 efficient: four sentences covering purpose, usage, behavioral notes, and tips. Every sentence adds unique value. Front-loaded with purpose. 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 feedback tool with 3 parameters (including nested object) and no output schema, the description is remarkably complete. It covers when to use, parameter details, rate limits, quota impact, and what to avoid. No gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by specifying that message should be 1-2 sentences (2000 chars max), and reiterating the meaning of each type. Also clarifies that context is optional and which fields are relevant. This extra guidance justifies a 4.

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

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

The description clearly states that the tool is for sending feedback (bug, feature, data_gap, praise) to the Pipeworx team. It uses specific verbs like 'tell' and 'broken, missing, or needs to exist,' and it is clearly distinct from sibling tools (none of which are for feedback).

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 specifies when to use each type: bug for wrong/stale data, feature/data_gap for missing tools, praise for positive experiences. Also gives clear instructions on what not to do (don't paste end-user prompt), which helps the agent choose correctly.

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

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

Beyond annotations (readOnlyHint, openWorldHint), the description adds key behavioral details: data source (CF analytics-engine), privacy (no PII), caching (5min-1h), and non-destructive nature.

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 use cases, then behavioral notes. No unnecessary words.

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

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

With single optional parameter, no output schema, and rich annotations, the description covers all necessary context including caching and data source.

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 value beyond the schema by explaining the semantics of window sizes (shorter for 'hot right now', longer for steady-state), complementing the enum values.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a window, distinguishing it from sibling tools like discover_tools and ask_pipeworx.

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

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

Explicitly lists three specific use cases (discovering hot data sources, confirming canonical tools, aligning use case with agent needs), providing clear guidance on when to use.

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

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

Annotations declare read-only, open-world, idempotent, non-destructive. The description adds behavioral details like Jaccard similarity thresholds, partition filtering, and fill check logic without contradiction.

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

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

The description is detailed and well-structured with clear sections for each mode, but it is slightly verbose with some redundant clarifications. Front-loaded purpose is good.

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

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

Given the complexity and no output schema, the description thoroughly covers inputs, internal logic, output structure (opportunities array, partition check, fill check), and edge cases (Jaccard similarity, placeholder filters).

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

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

Both parameters have schema descriptions, but the tool description adds significant meaning: it explains that event mode walks child markets and computes partition checks, while topic mode searches related events and flattens markets.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools like polymarket_fill_risk by noting custom sizing uses that 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 specifies when to use each mode (no args for trending scan, event for single-event, topic for cross-event) and when not to trade (realizable_edge_pp ≤ 0). It also points 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?

Annotations declare readOnlyHint and idempotentHint, and the description adds extensive behavioral context: caching (1h at KV level keyed on all knobs), response structure with segments and diagnostics, handling of Fed bets, and details on how empty segments are reported. 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 extremely long and detailed, covering model families, edge calculations, and response fields. While every sentence is informative, it is not concise and may overwhelm an agent. Front-loading is present but the density reduces overall conciseness.

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

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

Given the tool's complexity (9 parameters, no output schema, multiple segments), the description is remarkably complete. It explains the output structure, caching, diagnostics, Fed handling, and every knob's effect. No gaps remain for an agent to infer.

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 schema descriptions, but the tool description adds significant extra meaning: explaining knobs like min_liquidity and max_spread_pp as tradeable-edge filters, the role of slippage_pp, and the difference between min_kelly and min_partition_leg_kelly. This goes well 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 scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It distinguishes from siblings like polymarket_arbitrage and edge_tracker by focusing on discovery and three specific segments. The phrase 'Built for "what should I bet on today"' nails the 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 explicitly positions the tool for discovery ('what should I bet on today') and explains its scope. However, it does not provide explicit when-not-to-use guidance or compare directly with alternative sibling tools like polymarket_arbitrage or edge_tracker, leaving the agent to infer boundaries.

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

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

Annotations already mark the tool as readOnlyHint=true, idempotentHint=true, and not destructive. The description adds significant context beyond annotations: it explains the data source (daily snapshots), response structure (tracked, expired, snapshot_dates), and limitations (60-day TTL, not intraday). 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 well-structured, starting with the core purpose and then listing response fields and limitations. It could be slightly more concise, but all sentences add value and it is not overly verbose.

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

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

With no output schema, the description fully explains the return value: tracked[], expired[], and snapshot_dates[] arrays with their fields. It also covers data source and limitations, making the tool self-contained for a comprehensive understanding.

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 both parameters. The description adds minor additional context like 'clamp 2-30' for days and snapshot family meaning for window, but mostly repeats the schema. Meets the baseline for high coverage.

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

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

The description clearly states the tool provides 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers the specific question about edge existence and decay. It distinguishes itself from siblings by focusing on historical persistence rather than current edges, as implied by the sibling list including 'polymarket_edges'.

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

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

The description implies use when needing edge history and trend analysis, and mentions limitations like 60-day TTL. However, it does not explicitly list when not to use or mention alternative tools like 'polymarket_edges' for current edges only, though this is implied.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint as false. The description adds critical behavioral context: it walks the order-book ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, and verdict; for baskets it warns about thin_legs and forced_directional_risk. This adds rich behavioral detail beyond the annotations without contradiction.

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

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

The description is long but well-structured: it starts with the core purpose, then details each mode using clear headers (SINGLE-MARKET, BASKET), and ends with usage context. While every sentence adds value, some phrases could be tightened (e.g., 'forced_directional_risk naming the arms most likely to strand you unhedged'). Overall, it earns its length given the tool's complexity.

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

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

Despite lacking an output schema, the description enumerates all return fields for both modes, including edge cases like thin_legs and forced_directional_risk. It covers the tool's complete output behavior, making the description self-contained for an AI agent to understand what it will receive.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains that for single-market, size_usd means 'max spend on buys, target proceeds on sells', while for basket it means 'settlement notional S (shares per leg)'. It also clarifies the default side logic for basket ('auto — sell if partition sum > 1, buy if < 1'). This transforms the parameters from opaque fields to meaningful inputs.

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

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

The description starts with a precise verb+resource combination ('Realizable-vs-theoretical edge check against live CLOB order-book depth'), immediately distinguishing single-market and basket modes. It explicitly contrasts with sibling tools (polymarket_arbitrage, polymarket_edges) by stating when to use this tool before them, ensuring clear differentiation.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It further explains the risks of not using it ('partial basket fills convert an arb into an unhedged directional position'), which serves as a strong when-not-to-use warning.

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

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

The description goes far beyond the annotations, which declare read-only, idempotent, and non-destructive. It details safety fields (compatibility_warning, temporal_alignment, skipped_cross counters) and explains when the tool may return no actionable spreads due to bet shape mismatches or temporal misalignment. No contradiction with annotations.

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

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

The description is relatively long but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds useful information about modes, response structure, or edge cases. It is slightly verbose in the last few sentences but still efficient for the complexity.

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

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

Given the complexity of matching events across venues and the absence of an output schema, the description comprehensively explains the response structure (leg-by-leg prices, top_spreads_pp) and all safety fields. It covers compatibility warnings, temporal alignment, and skipped cross counters, ensuring the agent understands potential pitfalls.

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

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

The input schema covers all three parameters (topic, kalshi_event_ticker, polymarket_event_slug) with descriptions. The description adds significant value by listing the 10 valid topic values, explaining the override logic, and providing usage examples. The schema coverage is 100%, so baseline is 3, but the extra detail justifies a 4.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It uses specific verbs ('compute', 'compare') and explicitly distinguishes from sibling tools like 'polymarket_arbitrage' by focusing on spread across two venues.

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 defines two modes (topic shortcuts and explicit tickers) and provides guidance on when spreads are meaningful (when compatibility_warning is not triggered, temporal_alignment is true). However, it does not explicitly mention alternative tools for comparison, though the sibling list implies this is the unique cross-venue spread 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 indicate read-only, idempotent, non-destructive behavior. The description adds scoping details and the effect of omitting key, but does not disclose return behavior (e.g., what happens if key not found, format of the list).

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

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

The description is concise with two substantive sentences. It front-loads the action and then adds context. Could be slightly more structured, but no extraneous words.

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

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

Given the simple tool (1 param, annotations present), the description covers purpose, usage, scoping, and pairing. However, it lacks explicit documentation of return format, which is a minor gap for a retrieval tool.

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

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

The input schema has 100% coverage with a clear description for the one optional parameter. The tool description adds value by explaining omission behavior, scoping, and pairing with sibling tools, going beyond the schema alone.

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

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

The description uses specific verbs ("retrieve", "list") and identifies the resource (values saved via remember). It clearly distinguishes itself from sibling tools remember and forget, and provides concrete examples of usage (ticker, address, notes).

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

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

The description explicitly states when to use the tool (look up previously stored context) and provides examples. It mentions pairing with remember and forget, but does not explicitly state when not to use it, though the context is clear enough for a retrieval 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 indicate readOnly, openWorld, idempotent, non-destructive. The description adds value by detailing returned fields (source, citation_uri, raw event payload) and the mark_read side effect (affects next call). 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?

Extremely concise and well-structured: one paragraph with clear sentences. Every sentence adds value, no fluff. Essential information 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?

No output schema, but description briefly covers return fields and parameter behavior. Sufficient for a simple polling tool with 5 optional parameters. Could elaborate on pagination or sorting, but 'most recent' and limit suffice.

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

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

Schema coverage is 100%, so baseline is 3. The description adds useful context (e.g., mark_read flags events as read for subsequent calls, limit default 50) but does not significantly surpass the schema's parameter descriptions.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifying it returns the most recent alerts with source, citation_uri, and raw payload. This distinguishes it from siblings like list_subscriptions or subscribe.

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

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

Provides clear context on filtering (type, since), mark_read behavior, and mentions that polling works fine, plus an alternative access method (GET registry.pipeworx.io/alerts.json). Lacks explicit 'when not to use' but siblings are distinct enough.

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

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

Adds behavioral context beyond annotations: fans out to multiple sources, fallback logic, soft-fail for patents, return structure. 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?

Well-structured with front-loaded examples. Each sentence adds value, though slightly lengthy; still efficient given the complexity.

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

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

Despite no output schema, the description adequately explains return format and error handling (soft-fail for patents). Comprehensive for an aggregation tool.

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

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

Schema coverage is 100%, but description adds meaning with examples (ISO date, relative shorthand) and typical values for the 'since' parameter, aiding correct usage.

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

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

The description clearly states the tool provides a change feed for a company covering SEC filings, news, and patents, with specific verbs and resource identification. It contrasts with entity_profile, distinguishing it from a sibling 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?

Explicit guidance to use entity_profile instead for static profiles, and example queries are given. Could be slightly more explicit about when not to use this tool, but the sibling list provides 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 provide idempotentHint=true, destructiveHint=false, readOnlyHint=false. The description adds detail: data is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours. It confirms that this is a write operation (not read-only) and non-destructive. 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 a single focused paragraph that front-loads the purpose immediately. Every sentence adds value: examples, usage scenario, persistence details, and pairing with other tools. No fluff or repetition.

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

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

Given no output schema, the description adequately covers what the tool does, when to use it, how it behaves, and how it fits with sibling tools. It explains persistence differences and pairing with recall/forget, making the agent fully informed.

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 key and value. The description adds context with examples (key: 'subject_property', value: 'any text') and explains the purpose of each parameter, reinforcing schema details and providing usage guidance.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' and provides concrete examples (resolved ticker, target address, user preference). It distinguishes from siblings like recall and forget by specifying that this is for storing, not retrieving or deleting.

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

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

Explicit guidance on when to use: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also mentions pairing with recall and forget, giving a complete workflow 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 confirm read-only, idempotent, and non-destructive behavior. Description goes beyond by explaining internal cascading lookups ('replaces 2-3 manual lookups') and detailing output structure per type, adding valuable 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?

Description is well-structured with examples first, then details. It is substantive but not overly verbose. Every sentence adds value, though the list of query examples could be slightly shortened without loss.

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

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

Despite lacking an output schema, the description fully explains return values for both supported types, including formats and citation URIs. It covers typical use cases and edge cases (e.g., auto-disambiguation for companies), making it complete for an ID resolution tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds extra meaning by specifying accepted input formats for value (ticker, CIK, name for company; brand/generic for drug) and mentioning output details like citation URIs, which helps agents use parameters correctly.

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 uses specific verb 'resolve' with resource 'entity', provides example queries like 'What's the ticker for...', and distinguishes this tool from siblings (e.g., entity_profile, compare_entities) by explicitly stating its role in converting names to IDs.

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 'Use FIRST whenever you have a name but need an ID', which gives clear when-to-use guidance. Does not explicitly mention when not to use, but the context is clear enough for typical scenarios. Could mention alternatives for already-known IDs.

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, and non-destructive behavior. The description adds value by explaining it probes each entity with ai_visibility_check, ranks by score, and returns detailed results (score, confidence, signal density). 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 four sentences, front-loaded with the main purpose, and every sentence adds value. No redundancy or 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?

No output schema, but the description adequately describes the return (ranked list with score, confidence, signal density per entity). For a tool with moderate complexity and rich annotations, this is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining that the first entity in the 'entities' array is treated as the subject, and by clarifying usage of 'models' and '_apiKey' (e.g., 'Omit for just workers-ai'). This elevates the score.

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

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

The description clearly states the tool compares AI visibility across multiple entities, ranks them, and returns a ranked list. It distinguishes from sibling tools like ai_visibility_check (which is a sub-operation) and compare_entities (which is generic) by focusing specifically on AI visibility and competitive audits.

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 it is useful for competitive AI-marketing audits and gives an example query. While it does not list alternatives or exclusions, the context is clear enough for an agent to understand when to use 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?

Annotations already declare safe read/idempotent behavior. Description adds significant context: fans out to deps.dev and bundlephobia, returns summary block and advisory details, and describes graceful degradation with partial failure handling (bundlephobia timeout, sources_failed list). Adds value beyond annotations.

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

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

Description is moderately long but well-structured: purpose first, then fan-out targets, use case, ecosystem limitations, and failure behavior. Every sentence adds value, though slight tightening could improve conciseness.

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

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

Given complexity (multiple sources, summary block, partial failures) and no output schema, the description covers return fields, behavior, and limitations comprehensively. Could mention pagination or rate limits but current detail suffices.

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

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

Schema coverage is 100% with parameter descriptions. Description adds context about scoped packages accepted and default version behavior (latest when omitted), and clarifies the expected format. Adds meaning beyond schema.

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

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

The description clearly states the tool's purpose as a composite check for evaluating an npm package across license, advisories, version history, and bundle size metrics. It contrasts with sibling tools which are broader research or analysis tools, establishing distinct purpose.

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

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

Explicitly states when to use: when an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also specifies ecosystem (npm only in v1) and directs PyPI/Maven/Cargo/Go to deps.dev:version directly, providing clear usage boundaries and 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?

Even though annotations already declare readOnlyHint and idempotentHint as true, the description adds significant behavioral details: uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, a 200K char cap with truncation and flagging, and that results include character offsets and similarity scores. This goes well 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 concise yet packed with information. It starts with the core purpose, then explains when to use, how it works, and pairs with another tool. Every sentence earns its place 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 no output schema, the description explains return format (top-N passages with offsets and similarity scores), constraints (200K char limit, truncation flag), and pairing advice. It covers input, behavior, and output comprehensively given the tool's complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by giving example queries for the 'query' parameter (e.g., 'supply-chain risk', 'fiscal year 2024 revenue') and re-emphasizing the character limit for 'text'. This provides practical context beyond the schema descriptions.

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

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

The description clearly states 'Semantic search INSIDE a fetched record,' using a specific verb and resource. It distinguishes itself from sibling tools by mentioning ask_pipeworx_grounded and explaining when to use search_within instead of cramming entire text into a prompt.

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

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

Explicit guidance: 'Use when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter.' Also suggests pairing with ask_pipeworx_grounded for grounding over relevant passages, giving clear contextual 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 provide readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds the OAuth requirement and delivery limitations (10/day SMS cap). However, it does not clarify idempotency behavior—whether repeated identical calls return the same subscription ID or create duplicates. With annotations present, the description adds moderate value but misses an opportunity to explain the idempotentHint.

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

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

The description is somewhat lengthy but well-structured, with clear sections for types and delivery. Each part adds essential information. It could be slightly more concise but remains readable and front-loaded.

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

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

Given no output schema, the description covers prerequisites, supported types, delivery channels, and limitations. It adequately explains the tool's functionality and side effects, though it does not describe the exact subscription object structure beyond the ID.

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 goes beyond by providing concrete examples for each type (e.g., '5.02' = officer change) and detailed delivery channel behavior (e.g., webhook HMAC signing, auto-disable after 10 failures). This significantly enhances understanding beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It differentiates from siblings like list_subscriptions and unsubscribe.

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

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

The description includes when to use (setting up monitoring), prerequisites (Pipeworx OAuth account), and exclusions (anonymous/BYO cannot persist). It provides type-specific guidance and delivery options, though it could be more explicit about when not to use 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds valuable context: it is the onboarding entry point, returns categorized examples drawn from a live catalog, and lists example categories. This supplements the annotations with usage-specific behavior.

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

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

The description is relatively long but front-loaded with example queries, which is appropriate for an onboarding tool. Every sentence provides useful information; there is no wasted text. It could be slightly more concise, but the length is justified by the complexity of the tool's purpose.

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

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

Given no output schema, the description adequately explains the return value: category-bucketed example questions with tool+argument shapes. It covers when to use, how to call, what topics are available, and the tool's role in the onboarding flow. Complete for a discovery tool.

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

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

Schema coverage is 100% and the schema's description already lists the possible topic values. The description adds the advice to omit the parameter for a cross-category spread, but this is more usage guidance than parameter meaning. Since the schema already carries the burden, the description adds modest value.

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

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

The description clearly states the tool's purpose: an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It uses specific verbs ('suggest questions', 'show me examples') and distinguishes from sibling tools by positioning it as the first tool to use when the agent doesn't know what Pipeworx can do.

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

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

Explicitly states to use this FIRST when you do not yet know what Pipeworx can do, and provides guidance on calling with no arguments for full spread or with a topic to focus. However, it does not explicitly mention when not to use it or when alternatives might be better, though the context implies it's for initial exploration.

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

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

The description adds significant context beyond annotations: it clarifies that the row is deactivated, not deleted, and that historical events remain available via recent_alerts. No contradiction with annotations.

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

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

Two sentences that are front-loaded with the main purpose. Every word is necessary; no fluff.

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

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

For a simple tool with one parameter, no output schema, and annotations present, the description covers purpose, ownership constraint, and behavioral nuance (soft deactivation). Fully complete.

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

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

Schema coverage is 100% and the description does not add any additional meaning beyond the schema's parameter description for 'id'. Baseline score of 3 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 'Cancel a subscription by id.' It uses a specific verb (cancel/unsubscribe) and resource (subscription), and distinguishes well from siblings like subscribe and list_subscriptions.

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

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

It explicitly mentions ownership enforcement ('you can only cancel your own subscriptions') and refers to recent_alerts for historical events. While it doesn't list alternatives, the context is clear.

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

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

Beyond annotations (readOnly, openWorld, idempotent), description discloses the two internal pipelines, the verdict types (confirmed, approximately_correct, refuted, etc.), return of actual value with pipeworx:// citation, and the fact that it replaces 4-6 sequential calls. No contradiction with annotations.

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

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

One dense paragraph that front-loads purpose with common query forms. Every sentence serves a purpose—examples, processing paths, output format, efficiency note. Slightly long but appropriate for the tool's complexity; could be improved with bullet points for readability.

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

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

Given 2 parameters, no output schema, and sibling tools, the description covers all essential aspects: input examples, processing logic, output structure (verdict, value, reasoning), and performance benefit. The agent has everything needed to invoke the tool correctly.

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

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

Schema coverage is 100% and both parameters have clear descriptions. The description adds extra context: explains tolerance_pct overrides claim wording and ties to 'exact percent-delta math' for structured claims, while claim parameter examples illustrate usage. This adds meaningful guidance 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 starts with concrete examples and clearly states 'natural-language claim verification against authoritative sources'. It distinguishes two processing paths (structured SEC EDGAR for company-financial claims, grounded pipeline for others), making the tool's scope precise and differentiating it from sibling tools like ask_pipeworx or deep_research.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' Describes two specific claim types and their corresponding verification paths, providing clear context. Lacks explicit 'when not to use' statements, but the coverage is comprehensive enough for most scenarios.

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