Phoenix Number

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. Description adds value by explaining cost implications (free vs BYO key) and return format (per-model {score, confidence, signals, raw_response}). 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?

Three sentences, no fluff. First sentence states purpose and output, second explains model usage, third lists use cases. Front-loaded with key 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?

Describes return format and model selection. No output schema but return details given. Covers all 4 parameters and their relationships. Could mention limits or timeout, but sufficient for typical use.

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

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

Schema description coverage is 100%, providing baseline of 3. Description adds extra context beyond schema: clarifies that 'models' defaults to workers-ai, and '_apiKey' is only needed for anthropic model. Also explains how 'context' helps disambiguate.

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

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

Description clearly states 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' Specifies verb 'probe', resource 'LLMs', and output format. Distinguishes from siblings like 'ask_pipeworx' and 'scan_competitor_ai_presence' by focusing on visibility scoring.

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

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

Explains default model (free Workers AI) and how to probe Anthropic with BYO key. Lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Does not explicitly state when not to use or contrast with specific sibling tools, but provides adequate context for selection.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds critical context about internal routing to 4,945 tools, filling arguments, returning structured answers with citations, and tier compatibility, which enhances understanding beyond the annotations.

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

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

The description is front-loaded with a strong 'PREFER OVER' directive, structured with purpose, usage, examples, and alternatives. While slightly verbose (lists many source types), every sentence adds value. Could be trimmed but remains efficient.

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

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

Given the tool's complexity with no output schema, the description covers core functionality, usage context, alternative tools, example queries, citation format, and tier information. It is sufficiently complete for an LLM to use correctly.

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

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

Schema coverage is 100% with all parameters documented as aliases for 'question'. The description adds no further detail beyond what the schema provides. A score of 3 is appropriate per the rubric for high schema coverage.

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

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

The description clearly states the tool answers factual questions using authoritative structured data from thousands of sources, and explicitly distinguishes from siblings like ask_pipeworx_grounded and deep_research, making differentiation straightforward.

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

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

Provides explicit guidance to prefer over web search, lists concrete query types, gives usage examples, and details when to escalate to more specific or broader tools. This leaves little ambiguity for an LLM.

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 that already mark it as read-only, idempotent, and open-world, the description adds critical behavioral details: the specific routing improvement (source-preference ranking when a source is named in the question) and the fact that it is a live experimental edge with no fallback. This enriches the agent's understanding of how the beta differs from the stable version.

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—only four sentences—and front-loaded with the essential identity (beta, identical router). It efficiently communicates the purpose, the experimental improvement, usage guidance, and fallback behavior without any redundant or filler content.

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 (a beta router with thousands of tools) and the absence of an output schema, the description adequately covers the key contextual aspects: what it does, how it differs from the stable version, how to use it, and its experimental nature. It could perhaps elaborate on the specific routing improvement more, but overall it is sufficiently complete for effective agent usage.

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

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

The input schema has 100% coverage with clear aliases and descriptions for the 'question' parameter. However, the description does not add any additional semantic meaning beyond what the schema already provides. It only states 'same arguments' without elaboration. 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 it is the beta version of ask_pipeworx, a universal router with exactly the same 4,945 tools and arguments. It distinguishes itself from the stable sibling by highlighting its candidate routing improvements and experimental nature. The verb 'ask' plus the resource 'Pipeworx Beta' with specificity on capabilities makes the purpose unambiguous.

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

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

The description advises using it 'exactly like ask_pipeworx when you want the newest routing' and notes that results are compared to the stable router. It sets clear expectations by stating it is a full working router and does not fall back to anything. While it does not explicitly list when not to use or compare with other siblings beyond ask_pipeworx, the context is sufficient for the intended experimental use case.

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

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

Annotations already provide safety hints, but the description adds detailed return format including evidence, confidence, and refusal reasons. No contradiction with annotations.

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

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

Description is slightly long but well-structured and front-loaded with the key concept. Every sentence adds information without redundancy.

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

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

Covers all necessary aspects: purpose, mechanism, return format, usage guidelines, cost trade-off, and refusal scenarios. No gaps given the annotations and schema.

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

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

Schema coverage is 100%, but the description adds value by explaining that the tool accepts multiple aliases for the question parameter and clarifies how the question is used (routing/fetching).

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 hallucination-resistant answer mode for high-stakes reads, and differentiates it from the sibling 'ask_pipeworx' by explaining the extraction behavior.

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

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

Explicitly says when to use (when answers will be quoted, cited, or acted on) and when not to (prefer ask_pipeworx for casual lookups), with specific examples like financial verdicts or medical lookups.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral context: parallel fan-out to multiple sources, status codes for low-confidence matches and closed markets, tradeability warnings, resolution-rule risk parsing, response size control via include_raw, and detailed resolver contract. This far exceeds the minimal annotation coverage.

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

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

The description is long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It front-loads the core purpose and progressively adds detail. While every sentence adds value, the overall length could be trimmed for quicker consumption. It earns a 4 for organized depth.

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

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

Given the tool's complexity (multiple data sources, classification, response shapes, edge cases), the description covers all relevant aspects: input, output behavior, error states (low-confidence, closed markets, wide spreads), safety mechanisms, and resolution-rule risk. No gaps are apparent despite the absence of an output schema.

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

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

Schema coverage is 100% (all three parameters described). The description significantly enriches parameter meaning: for 'market' it explains three input formats with examples; for 'depth' it defines quick vs thorough; for 'include_raw' it clarifies response size implications and use cases (recompute deltas, cite observations). The fan-out examples also implicitly illustrate the depth parameter's effect.

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

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

The description clearly states the verb-resource pair: 'Research a Polymarket bet by pulling the relevant Pipeworx data.' It specifies input formats (slug, URL, question text) and explicitly differentiates from siblings by detailing the comprehensive fan-out and evidence packet approach, which is unique among sibling tools.

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

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

The description provides explicit use cases: 'Use for should I bet on X, what does the data say about Y, or is there edge in Z.' It also gives fan-out examples for different bet categories. However, it does not directly contrast with alternative tools like polymarket_edges or polymarket_arbitrage, leaving some ambiguity about when to choose 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?

Beyond annotations (read-only, open-world, idempotent), the description reveals data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. It also notes the efficiency gain of replacing 8–15 lookups.

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

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

The description is comprehensive but slightly lengthy. It front-loads with common query phrases and uses clear structure. Every sentence adds value, though some could be condensed.

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 an output schema, the description sufficiently explains return format (paired data with citation URIs), data source variations, sorting behavior, and entity validation. It covers all necessary aspects for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the meaning of 'type' values (company vs. drug) and what data each returns, as well as providing examples for 'values' and clarifying min/max items.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in a single call. It includes example triggers like 'compare X and Y' and explicitly distinguishes itself from sequential single-pack lookups.

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

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

The description advises preferring this tool over sequential lookups when comparing entities. It explains when to use which type (company or drug) and what data each retrieves, but does not explicitly list when not to use it or mention alternative tools by name.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds extensive behavioral details: parallel decomposition, gap recovery, contradiction scanning, field structure (findings, gaps[], contradictions[]), timing expectations (15-90s), and excerpting behavior for long records. 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 but well-structured and front-loaded with critical account/alternative info. Every sentence adds value; however, a slight condensation could improve scanability. For the complexity, it's appropriately sized.

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

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

Given no output schema, the description fully covers return values (findings packet with verbatim evidence, confidence, source, citation, gaps, contradictions, hop field). It addresses edge cases (news topics return gaps[], large records excerpted). The depth modes and time expectations are explained. Very complete for a complex 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 schema descriptions are minimal. The main description adds substantial value: explains the depth enum in detail (quick=3, standard=5 with gap recovery, thorough=8 with iterative chase) and clarifies that question can be broad/multi-part. This goes well 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 clearly defines the tool as grounded multi-source research over structured data, contrasting with sibling ask_pipeworx. It specifies the exact scope (1300 sources, not open-web) and the type of questions it handles (broad/multi-part). The verb 'research' and resource 'structured data sources' make the purpose unmistakable.

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?

Excellent usage guidance: explicitly states when to use this tool vs ask_pipeworx (single lookups, breaking news). Also covers account requirements and provides a free alternative for non-signed-in users. The depth parameter descriptions help select the right level of research.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, confirming safe read-only behavior. The description adds that results include 'full input schemas (with curated examples)' and are 'ready to call directly', which is valuable context beyond annotations.

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

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

The description is a single paragraph but efficiently organized: purpose, usage guidance, domain examples, and return format. Every sentence adds value, with no fluff. It is front-loaded with the key verb and resource.

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 what is returned (names, descriptions, schemas, examples) and notes it's ready to call. It covers sufficient behavioral detail for a discovery tool with safe annotations. Minor gap: no mention of pagination or error handling, but not critical.

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

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

Schema coverage is 100% with descriptions for all parameters. The description provides example queries and notes aliases, adding some nuance. However, most parameter semantics are already covered by the schema, so additional value is limited. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It enumerates many specific domains (SEC filings, FDA drugs, etc.), making it distinct from sibling tools which are more specialized. The verb 'discover' matches the resource 'tools'.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and advises 'Call this FIRST when you have many tools available.' This provides clear context for when to use, though it does not explicitly list 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already convey non-destructive, read-only behavior. The description adds context about patents soft-failing and the parallel fan-out nature, which is helpful but not extensive.

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 efficient, front-loading examples and purpose. It lists data sources and return fields in a clear, readable manner, though could be slightly more structured with bullets.

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?

Without an output schema, the description thoroughly details all return fields (cik, recent_filings with URIs, fundamentals, patents caveat, news, LEI). It provides sufficient context for an agent to understand the tool's capabilities and limitations.

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 elaborates on parameters: type is limited to 'company', value accepts ticker or CIK with examples, and explicitly states names are not supported, directing to resolve_entity. This adds significant meaning beyond the schema.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company in one call, with specific examples ('Tell me about X', 'research Acme') and lists data sources. It distinguishes from siblings like 'resolve_entity' by specifying it handles tickers/CIKs not names.

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

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

The description explicitly recommends using this tool over chaining single-pack lookups for holistic views, and advises using resolve_entity if only a name is available. It also notes the patents source may soft-fail, guiding expectations.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true, informing that deletion is safe to retry. The description adds context about clearing sensitive data, which is useful beyond annotations, but does not disclose any further behavioral details such as return values or error handling.

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: two sentences, no wasted words. First sentence states purpose, second provides usage guidance and related tools. Front-loaded with key information.

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

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

For a tool with one parameter and no output schema, the description covers purpose, usage context, and relationships to siblings. Annotations cover safety and idempotency. No gaps identified.

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 the 'key' parameter described as 'Memory key to delete'. The description does not add extra meaning beyond 'by key', so it meets the baseline for high coverage but adds no additional 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?

Clearly states the action ('Delete') and resource ('previously stored memory by key'). Distinguishes from siblings by mentioning pairing with remember and recall, which are listed as sibling tools.

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

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

Explicitly specifies when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also provides companion tools: 'Pair with remember and recall', aiding selection decisions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds detailed behavioral context: fetches page, extracts title/description/key links, emits standard markdown format, and produces a single text blob, significantly enhancing beyond annotations.

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

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

The description is a single, focused paragraph of 4 sentences, front-loaded with the purpose, followed by process and use cases. No unnecessary words or repetition, earning its place.

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

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

Given no output schema, the description explains the output format (standard llms.txt markdown, single text blob) and the extraction process. For a simple read-only tool with minimal parameters, this covers all essential information.

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

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

With 100% schema description coverage, both parameters (url, max_links) are already well-described in the schema. The description does not add extra meaning beyond restating the default/max for max_links, so baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb, resource, and goal. It implies distinction from siblings like ai_visibility_check by focusing on file generation rather than visibility scanning.

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 (client indexing, personal drafting, competitor auditing), providing clear context for when to use. It does not explicitly mention when not to use or compare to alternatives, but the context is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds value by specifying that it only returns the caller's subscriptions and lists the return fields. 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?

Two sentences, no filler, front-loaded with the action. Every sentence serves a purpose: first states what, second gives usage context.

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

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

Given no output schema, the description includes return fields. The schema covers parameters. Annotations cover safety. For a simple list tool with one optional param, it is complete and 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% with a clear description for the only parameter (include_inactive). The tool description does not repeat or add extra meaning to the parameter, so baseline 3 is appropriate.

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

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

Clearly states it lists the caller's active subscriptions with specific fields (id, type, params, timestamps, fire_count). Distinguishes from siblings like subscribe/unsubscribe by mentioning use cases: review before adding more or find id to cancel.

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

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

Explicitly says when to use: 'review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and indirectly tells when not to use (e.g., for other subscription operations).

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

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

Annotations already cover key traits (read-only, idempotent, non-destructive). The description adds that the output is random, which is behavioral context not in annotations. No contradiction.

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

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

The description is two sentences with zero wasted words. It is front-loaded with the main action and includes a humorous but harmless flourish.

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 extreme simplicity (zero parameters, output schema exists), the description is complete. It explains the random nature and lack of inputs, satisfying all informational needs.

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

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

There are no parameters, and schema coverage is 100%. The description adds no parameter information beyond what the schema provides. 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 returns a random number presented as a temperature. The verb 'returns' and resource 'random number' are specific. No sibling tools have similar functionality, so it is easily distinguishable.

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

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

The description says 'No inputs required,' which implies usage context (just call it). However, it does not provide explicit when/when-not guidance or alternatives. For such a simple tool, this is adequate but not exemplary.

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?

Disclosure includes non-obvious traits: rate-limited to 5 per day, free, no quota impact, and that team reads digests daily. These add significant value beyond the annotations, which only indicate non-read-only and non-destructive.

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: purpose first, then usage guidance, then constraints. Every sentence serves a purpose, though slightly verbose; could be trimmed slightly without losing value.

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

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

Covers all necessary aspects: what the tool does, when to use it, how to use parameters, behavioral constraints, and what the team does with feedback. No output schema needed; completeness is high for this simple tool.

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

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

Though schema coverage is 100%, the description adds meaningful context: explains the enum values in plain language, clarifies the 'context' object fields, and instructs how to write the message (be specific, in terms of tools/packs).

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: sending feedback (bug, feature, data_gap, praise) to the Pipeworx team. It distinguishes from sibling tools, all of which are for queries, research, or alerts, not 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?

Explicitly specifies when to use each feedback type, advises against pasting end-user prompts, and notes rate limits and that it's free—providing clear context for when to use this tool versus alternatives.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint = false. The description adds valuable behavioral details: data source ('CF analytics-engine'), no PII, caching duration (5min-1h depending on window). 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 yet comprehensive, using bullet-like formatting for use cases. Every sentence adds value, and the structure is front-loaded with the core functionality followed by context.

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

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

Given the tool's simplicity (1 optional parameter, no output schema), the description covers return values, use cases, data source, privacy, and caching. It leaves no ambiguity about what the tool provides or how to use it.

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

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

Schema coverage is 100% with a description for the 'window' parameter. The description further enriches by explaining that shorter windows show immediate trends and longer windows steady-state demand. This adds meaning beyond the schema's enum listing.

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, top packs, and total call volume over a recent window'. It uses a specific verb ('Returns') and resource, and distinguishes itself from sibling tools by focusing on aggregated trending data rather than individual queries or entity profiles.

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

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

The description explicitly lists three specific use cases (discovering hot data sources, confirming canonical tools, aligning use cases). It also explains the trade-off between window choices ('shorter windows surface what's hot; longer windows show steady-state demand'). However, it lacks explicit guidance on when not to use this tool, missing a minor opportunity.

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 and idempotentHint. The description goes far beyond these, detailing the algorithms (monotonicity violations, partition_sum checks), semantic anchor (Jaccard similarity threshold), partition filter (placeholder slugs), and fill check logic (theoretical_edge_pp vs realizable_edge_pp). 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 somewhat lengthy but every sentence adds value, covering purpose, modes, algorithms, edge cases, and response interpretation. It is front-loaded with the core purpose and then details. Could be more structured with bullet points or sections, but remains 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 tool's complexity (two modes, multiple algorithmic checks, fill verification), the description covers all necessary aspects: how to invoke each mode, what checks are performed, interpretation of response fields, and references to sibling tool for custom sizing. No output schema exists, but the description explains response structure sufficiently.

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

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

Schema description coverage is 100% with both parameters having descriptions. The description adds meaning beyond schema by providing concrete examples (event slugs like 'fed-decision-may-2026', topic seed questions) and explaining behavior (e.g., 'Full Polymarket URLs also accepted' for event, and how topic searches related events). This adds value but schema already does a good job.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes from sibling tools by specifying the algorithmic approach and two distinct modes (event and topic), with examples. This provides specific verb+resource and 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 gives clear guidance on when to use each mode: 'Call with NO args for a trending_scan...' and recommends event for a specific market, topic for cross-event scanning. It explains benefits of cross-event mode. However, it could explicitly state when NOT to use each mode or mention alternatives, but overall it provides good usage context.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive behavior. The description adds extensive behavioral detail: edge calculation methods, Kelly sizing, slippage, liquidity filters, caching, output structure with diagnostics, and caveats about Fed data reliability. 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 very long (multiple paragraphs) and includes detailed technical explanations that could be condensed. While well-structured, it lacks conciseness and may overwhelm the agent.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is remarkably complete. It explains the output structure in detail, caching behavior, edge calculation formulas, and diagnostic information, fully compensating for missing output schema.

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

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

The schema covers all 9 parameters with descriptions. The tool description adds usage context and behavioral implications for each parameter (e.g., 'skips opportunities that are too small' for min_kelly, 'Tradeable-edge filter' for max_spread_pp), which adds value 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 clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a specific use case 'what should I bet on today.' It distinguishes itself from siblings like polymarket_arbitrage by focusing on edge detection.

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

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

The description provides clear context for when to use the tool (discovering betting opportunities) and explains why Fed bets are excluded. However, it does not explicitly mention alternatives or when not to use it, relying on implied differentiation.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds significant behavioral detail: it computes trend and decay from the latest snapshot, handles expired opportunities, explains snapshot gaps, and notes limitations (60-day TTL, decay from daily closes). This exceeds what annotations provide.

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

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

The description is detailed and well-organized, front-loading the core purpose. Every sentence adds useful information, though it could be slightly more concise. Still, it is effective for an agent.

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

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

Given the complexity of time-series edge analysis and the absence of an output schema, the description fully explains the output structure (tracked[], expired[], snapshot_dates[]) and key fields. It also covers limitations and assumptions, making the tool's behavior predictable.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by specifying defaults (days=14, window='1wk'), clarifying the meaning of 'window' (snapshot family), and explaining the lookback clamp. This enriches the schema information.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It distinguishes itself from sibling tools like 'polymarket_edges' by focusing on time-series analysis rather than raw edge data.

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

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

The description explains when to use the tool (e.g., to differentiate between a new wide edge and an old one) and what it answers. While it does not explicitly state when not to use it or provide alternatives, the context is clear and sufficient for an agent to decide.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: what the tool returns per mode, default behavior for basket side (auto from partition sum), and key risks like thin legs and forced directional risk. No contradiction with annotations.

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

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

The description is well-structured with bolded headings for modes and clear separation of concepts. Every sentence adds value, covering purpose, usage, parameters, behavior, and return values. It is appropriately sized for the tool's complexity, with no redundancy.

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

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

Despite no output schema, the description thoroughly enumerates return fields for both modes, including specific field names and their meanings. It explains edge cases like forced directional risk and partial fills. For a complex financial tool, this is highly complete and self-contained.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds meaning beyond schema: explains required mutual exclusivity of market/event, clarifies size_usd interpretation (spend vs proceeds vs settlement notional), and describes default side logic for baskets. This provides context the schema alone does not.

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 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes between two modes (single-market and basket), specifies what each does, and lists return fields. This distinguishes it from sibling tools like polymarket_arbitrage and 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?

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains why with reasoning about theoretical overround not being capturable on thin books and partial fills creating directional risk.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description thoroughly explains behavioral traits: compatibility_warning triggers (shape mismatch or no semantic match), temporal alignment flag, skipped cross-type/subtype counters, and the fact that real spreads are rare. This far exceeds what annotations provide.

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

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

The description is long but well-organized into sections (modes, response, safety fields). Every sentence contributes useful detail. It could be slightly more concise, but the structure aids understanding.

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 (cross-venue comparison, safety fields) and the absence of an output schema, the description fully explains what the tool returns (leg-by-leg prices, top spreads, compatibility warnings). It covers edge cases and limitations, making it complete for an agent to use correctly.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds value by explaining the interaction between parameters (explicit overrides topic, topic auto-mapping) and listing valid topic values. While schema already defines types and examples, the description clarifies the operational semantics.

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

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

The description clearly states that the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It explains two modes (topic and explicit) and the response structure. This distinguishes it from sibling tools like polymarket_arbitrage, which likely focus on single-venue arbitrage.

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 guidance on when to use topic shortcuts vs explicit parameters and warns that most pre-mapped topics are not tradeable due to compatibility warnings. However, it does not explicitly contrast with alternatives like polymarket_arbitrage, leaving some ambiguity about when to choose 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 provide readOnlyHint=true. Description adds scoping detail (by anonymous IP, BYO key hash, or account ID) and the behavior of omitting key to list all keys. No contradictions.

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

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

Three sentences: core function, use case with examples and rationale, scoping and pairing. No superfluous words. Each sentence earns its place.

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

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

Simple tool (one optional param, read-only, idempotent) with full coverage of purpose, usage, parameter behavior, and sibling relationships. No output schema but description sufficiently implies return values.

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% (parameter 'key' described). Description adds that omitting key lists all keys, which is useful but not transformative beyond schema. Baseline 3 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?

Verb is specific ('Retrieve' or 'list'), resource is clearly defined (values saved via remember). Distinguishes from siblings by explicitly pairing with remember/forget. Provides concrete examples (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?

Explicitly states when to use (to look up stored context) and mentions scoping (by identifier). Implicitly excludes new info by stating 'without re-deriving from scratch'. Could be strengthened by explicitly contrasting with remember/forget, but pairing is mentioned.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, establishing safety. The description adds behavioral context: setting mark_read:true flags events as read so subsequent calls return only newer events. This goes beyond annotations without contradicting them.

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

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

Three sentences, each dense with purpose, return content, and usage guidance (filtering, mark_read behavior, polling alternative). No redundancy; front-loaded with core function.

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

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

Despite no output schema, the description covers return values (source, citation_uri, raw payload), filtering options, and mark_read behavior. Adequate for a 5-parameter all-optional tool, but could further detail edge cases (e.g., empty feed).

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

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

With 100% schema coverage, baseline is 3. The description adds value by explaining parameter usage: 'Filter by type (e.g. 'sec_8k') and/or since (ISO timestamp). Set mark_read:true to flag returned events read' and implies default limit of 50, supplementing 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 starts with 'Pull fired events from your subscription feed,' clearly stating the verb and resource. It then specifies returned fields (source, citation_uri, raw payload) and distinguishes itself from sibling tools like list_subscriptions by focusing on alert events rather than subscription management.

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

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

The description mentions 'Polls work fine; the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards,' indicating suitability for polling and providing an alternative access method. However, it does not explicitly state when not to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: fan-out to multiple sources, fallback logic (GDELT→GNews on rate-limit/5xx), soft-fail for USPTO due to API sunset, and output structure (changes grouped by source, total_changes count, citation URIs). 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 longer than average but every sentence adds value. It front-loads example queries and organizes information logically (sources, parameter details, output, sibling distinction). Some minor redundancy could be trimmed, but it remains efficient and well-structured.

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

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

No output schema exists, but the description fully explains what is returned (changes grouped by source, total_changes count, citation URIs). It covers source behavior, fallback, parameter semantics, and when to use alternative tools. For a 3-parameter tool with no output schema, the description provides complete contextual information.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by giving concrete examples for 'since' (ISO date and relative shorthand) and usage recommendation ('30d' or '1m'), plus clarifying 'value' can be ticker or CIK. While schema already covers basics, the extra context raises it above baseline 3.

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

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

The description provides specific verb-resource pairs ('change feed for a company') and lists exact use cases ('What's new with X', 'latest on Y'), clearly distinguishing from sibling 'entity_profile' which handles static profiles. It names the sources (SEC EDGAR, GDELT, GNews, USPTO) and output structure, making the tool's function unmistakable.

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 this tool (for recent changes over a window) and when to use the sibling 'entity_profile' ('when you want the static profile... regardless of window'). Also provides practical guidance for the 'since' parameter ('Use '30d' or '1m' for typical monitoring').

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

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

Annotations already indicate idempotentHint=true. The description adds valuable behavioral context: 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours' and 'scoped by your identifier'. 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 concise (4 sentences), front-loaded with purpose, and well-structured: purpose, usage, storage details, sibling pairing. Every sentence adds value with no fluff.

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

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

Given the simple tool (2 params, no output schema, annotations present), the description covers purpose, usage, behavior, parameters, and sibling tools comprehensively. It is complete for the agent to use correctly.

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

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

Schema provides 100% coverage for both parameters. The description adds examples for key ('subject_property', 'target_ticker') and clarifies value type ('any text — findings, addresses, preferences, notes'), adding meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It specifies the resource ('key-value pair'), uses specific verbs, and distinguishes from siblings by mentioning 'recall' and 'forget'.

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

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

The description provides clear context on when to use: 'Use when you discover something worth carrying forward... so you don't have to look it up again'. It gives examples but does not explicitly state when not to use, though pairing with recall/forget implies the scope.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds that each call cascades through several lookup endpoints, replacing 2-3 manual lookups. It also details the return format for each type, including citation URIs. No contradictions.

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

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

The description is moderately long but front-loaded with user-friendly examples and clear structure. Every sentence adds value (usage advice, type details, internal behavior). Could be slightly shortened without losing clarity, but it's efficient overall.

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

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

With no output schema, the description fully explains return values per type (ticker+CIK+company_name+URI for company; RxCUI+ingredient+brand+URI for drug). It also explains the internal cascading behavior and that it replaces multiple manual lookups. Given the tool's moderate complexity, this is complete.

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

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

Schema covers 100% of parameters, but the description adds substantial meaning: for 'type', it lists supported values and what each returns; for 'value', it explains accepted formats (ticker, CIK, name for company; brand or generic for drug) with examples. This goes beyond the schema description.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers with specific examples and distinguishes between supported types (company, drug). It uses strong verbs like 'resolve' and specifies the output (ticker, CIK, RxCUI, etc.). It differentiates from siblings by being the primary ID lookup 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?

Explicitly says 'Use FIRST whenever you have a name but need an ID.' This gives clear when-to-use guidance. It does not explicitly mention when not to use or compare to siblings, but the instruction to use first implies precedence. Could be improved by noting alternatives for deeper entity info.

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 that it probes each entity with 'ai_visibility_check', ranks by score, and returns a ranked list with score, confidence, and signal density. This goes beyond annotations by detailing the internal process and output structure.

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

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

The description is three sentences long, with the first sentence front-loading the core purpose. Each sentence adds distinct information: purpose, mechanism+output, and use case. There is 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?

With no output schema, the description adequately covers the return value (ranked list with score, confidence, signal density). It also explains the process (probes via ai_visibility_check) and parameter constraints (2-8 entities). However, it does not mention behavior for missing entities or error cases, which would improve completeness.

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

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

Schema coverage is 100%, baseline 3. The description adds value for key parameters: for 'entities', it explains that the first entry is the 'subject' for narrative; for 'context', it says 'disambiguates common names'; for '_apiKey', it clarifies 'only if anthropic is in models'. These details enhance 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 compares AI visibility across multiple entities side-by-side. It specifies the verb 'scan' and resource 'competitor AI presence', and distinguishes from sibling tools like 'ai_visibility_check' (single entity) by emphasizing multi-entity comparison. The example query reinforces its 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?

The description explicitly states it is 'useful for competitive AI-marketing audits' and gives an example. It implies usage when comparing multiple brands, but does not explicitly state when not to use it or directly mention alternative tools. Context signals show siblings like 'ai_visibility_check' for single entity, but the description does not formally contrast them.

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

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

Annotations indicate readOnly, idempotent, and non-destructive. The description adds valuable behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed lists timeouts. 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 somewhat long but each sentence adds value. It is front-loaded with the main purpose. Could be slightly tighter, but overall effective.

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

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

The description covers the composite nature, data sources, potential delays, partial failure behavior, ecosystem limitation, and return structure (summary block, advisories, links, alternatives). For a complex tool without output schema, this is highly complete.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds extra context: scoped packages are accepted for 'package', and default behavior for 'version'. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose as a composite 'should I add this npm package' check, specifying it combines deps.dev and bundlephobia data. It distinguishes from siblings by focusing on npm packages and composite functionality.

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

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

The description explicitly tells when to use: when an agent asks about package safety, popularity, or size. It also states what not to use: other ecosystems should use deps.dev directly. This provides clear guidance 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds details about internal algorithm (BGE-base-en embeddings, cosine similarity, 500-char windows), cap at 200K chars with truncation and flagging, and that each passage carries an offset for verification.

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

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

The description is a single, well-structured paragraph that front-loads the core purpose, then gives examples, pairing advice, and technical details. It is concise but covers all necessary aspects.

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

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

The tool has no output schema, yet the description clearly explains the return value: 'top-N passages with character offsets and similarity scores.' It also covers limits, algorithm, and pairing with a sibling tool. The agent has enough information to use this tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context beyond the schema: for 'text' the max char limit, for 'query' examples of natural-language queries, and for 'limit' the range and default. It also explains the 500-char windows and truncation behavior.

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' and provides concrete examples (SEC 10-K, article, tool result). It distinguishes from sibling tools like ask_pipeworx_grounded by explaining the role of searching within a retrieved document.

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

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

The description says 'Use when the record is too big to cram into the prompt' and explains how it saves context. It also suggests pairing with ask_pipeworx_grounded. It does not explicitly state when not to use, but provides sufficient 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 indicate not read-only, open world, idempotent, not destructive. The description adds detail: requires OAuth, type-specific behavior, delivery nuances (auto-disable webhook, SMS cap), and that feed is always on. It is transparent but lacks cost or broader rate limit info.

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 well-structured with type and delivery channel details. It earns its length with valuable information, though minor redundancy could be trimmed.

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 states the return value. It covers input schema completely, authentication requirements, and behavioral specifics. It is complete for a creation tool but could mention what happens on duplicate subscriptions (idempotent hint suggests safe retry).

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

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

Schema coverage is 100%, and the description adds substantial meaning: explains each enum type with examples (e.g., sec_8k with item codes), details param formats, and elaborates on delivery options (webhook HMAC signing, auto-disable). 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 it creates a proactive monitoring subscription and returns an ID. It distinguishes itself from siblings like 'unsubscribe' and 'list_subscriptions' by being a creation 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 specifies when to use (to set up monitoring on live data streams), prerequisites (Pipeworx OAuth account), and limitations (SMS cap, phone verification). While it doesn't explicitly contrast with all siblings, it provides sufficient context for correct 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?

Annotations already indicate readOnly, openWorld, etc. The description adds rich behavioral context: that it returns category-bucketed example questions with exact tool+argument shapes, drawn from a live catalog, and that it accepts an optional topic parameter to focus.

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

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

The description is somewhat long but effectively front-loaded with alternative phrases. It is well-structured, covering multiple aspects without unnecessary repetition. Could be slightly more concise but still efficient.

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

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

Entirely adequate for an onboarding tool with one optional parameter. It explains the return format despite no output schema, and covers the main usage scenarios (no args vs. with topic). No gaps identified.

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

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

Schema coverage is 100% with a description for 'topic'. The description adds extra meaning by listing possible values (finance, pharma, etc.) and explaining that omitting the parameter gives a full spread, going beyond the schema.

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

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

The description clearly states it is the onboarding entry point for learning what the agent can do. It uses specific verbs ('ask', 'returns') and distinguishes clearly from sibling tools like 'ask_pipeworx' by explaining it provides example questions with tool calls.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. This provides clear guidance on when to use it and implies 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?

Adds value beyond annotations: explains that the row is deactivated (not deleted) and historical events remain accessible via 'recent_alerts'. No contradiction with annotations (readOnlyHint=false, destructiveHint=false).

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

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

Two sentences, no fluff, front-loaded with the primary action and key constraints. Every sentence provides essential information.

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

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

The tool is simple with one parameter and no output schema. The description fully covers purpose, ownership, side effects, and implications for historical data, leaving no gaps.

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

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

Schema coverage is 100% with a clear parameter description ('Subscription id (uuid) returned by subscribe'). The description does not add further meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id' with a specific verb (cancel) and resource (subscription), and distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions') and explains side effects (deactivation vs deletion). Lacks explicit comparison to siblings or when not to use, but provides clear context.

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

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

Discloses behavioral traits beyond annotations: describes the two verification paths (structured vs. grounded), explains the return value (verdict, actual value with citation, reasoning), and notes it replaces multiple sequential calls. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint).

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, information-dense but well-structured. Front-loads core purpose and example queries. Every sentence serves a purpose, though could be slightly more structured (e.g., bullet points). Still effective and concise 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?

Covers all necessary aspects given tool complexity: explains the two verification paths, the verdict options, the output structure (value with citation, reasoning), and the replacement of multiple calls. No output schema, but description compensates sufficiently.

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

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

Schema coverage is 100% with both parameters described. The description adds meaning: explains how the claim is processed (NL parsing, entity resolution) and that tolerance_pct overrides the default implied by wording. This adds value 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?

Description starts with clear purpose: natural-language claim verification. Lists example queries and explicitly states it checks factual correctness against authoritative sources. Distinguishes between company-financial claims (SEC EDGAR + XBRL) and other claims (grounded pipeline), which differentiates it from siblings.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' Provides clear context for usage, though does not explicitly mention when not to use or alternative tools. The detailed explanation of the two processing paths gives strong guidance.

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