Rba

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context beyond these: the default model (Workers AI Llama-3.3-70b, free), the fact that probing Anthropic requires a BYO API key and that the user pays Anthropic directly, and the per-model response structure. This discloses important side effects (external API calls with cost implications) not covered by annotations, with 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 three sentences, front-loaded with the primary action, and every sentence serves a purpose: what it does, special configuration/cost, and return format. There is zero redundancy or fluff, making it easy to parse.

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

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

Despite having no output schema, the description explicitly lists the per-model return fields (score, confidence, signals, raw_response) and a combined view, covering the most critical return information. It also provides use cases and payment implications. It does not detail error handling or rate limits, but for a moderately complex probing tool with rich annotations, this is sufficient.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter semantics by explaining the default model when 'models' is omitted and clarifying that '_apiKey' is passed through to Anthropic and billed to the user. This goes beyond the schema's basic parameter descriptions, aiding the agent in choosing appropriate values.

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

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

The description opens with a specific verb ("Probe") and clearly identifies the resource (one or more LLMs) and the outcome (score visibility 0-100 per model). It distinguishes the tool from siblings like ask_pipeworx (a Q&A tool) and scan_competitor_ai_presence (which targets competitors), making its 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?

The description states clear use cases: "AI-marketing audits, pre-launch brand checks, competitive monitoring." This provides solid context for when to use the tool. However, it does not explicitly name alternatives or state when NOT to use it, so it stops short of full exclusionary guidance.

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

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

Annotations already declare read-only/idempotent/open-world, and the description adds meaningful behavioral context: routes to thousands of tools, fills arguments, returns citation URIs, one fast call. It also hints at a limitation (grounded sibling needed for verbatim evidence/confidence), which 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?

Description is front-loaded with 'PREFER OVER WEB SEARCH' and flows logically through usage, examples, and alternatives. It is verbose but every sentence serves a purpose; slight tightening could improve scannability.

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

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

For a complex routing tool with many siblings and no output schema, the description is remarkably complete. It explains return format (structured answer with stable URIs), scope (broad real-world domains), usage priority, and alternative escalation paths. Fully sufficient for an agent to select and invoke correctly.

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

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

Input schema covers 100% of parameters with descriptions and aliases documented. The description provides usage examples but adds no extra parameter-level semantics beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states the tool routes questions to 5,521 tools across verified sources and returns structured answers with citations. It explicitly differentiates from siblings (ask_pipeworx_grounded, deep_research) and positions itself as the default entry point.

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 when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE for most questions'), specific query types and examples, and when-not-to-use with named alternatives (ask_pipeworx_grounded, deep_research). Includes breaking-news nuance and coverage of 'every tier'.

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

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

The description goes beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by disclosing that no candidate is currently active, making it identical to ask_pipeworx, and that results are compared for routing decisions. It also explicitly states 'Falls back to nothing — this IS a full working router', which is critical behavioral context not inferable from 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 three sentences, each providing essential information: identity and scope, current state, and usage guidance. It is front-loaded with the most important fact (beta router identical to ask_pipeworx) and avoids redundancy, with no wasted words.

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

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

Given the tool's complexity (a universal router with thousands of tools) and lack of output schema, the description adequately explains its role, experimental nature, current equivalence to the stable tool, and expected behavior. It answers likely questions about reliability, fallback, and how it differs, making it complete for an agent to invoke correctly.

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

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

The input schema has 100% description coverage for all six parameters (all aliases for question), so the schema already documents them. The description adds that arguments are identical to ask_pipeworx, but this is redundant with the schema and doesn't provide additional semantic detail, aligning with the baseline of 3.

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

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

The description clearly identifies this as a beta version of ask_pipeworx with an identical universal router, specifying the same 5,521 tools, arguments, and response shape. It distinguishes it from the stable ask_pipeworx by highlighting candidate routing improvements and experimental status, making its purpose explicit.

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

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

It explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing', providing a direct usage directive. It also explains the comparison process against the stable router and clarifies that it is a fully working router, not a fallback, giving clear context on when to choose this tool over 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?

The description goes beyond annotations by detailing the return shape (answer, evidence, confidence, source, fetched_at, refusal_reason) and enumerating specific refusal reasons. It also notes the extra LLM call cost compared to ask_pipeworx. This supplements the readOnly/openWorld hints without contradiction.

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

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

The description is dense but well-structured, front-loading the core purpose and then providing routing details, return format, usage guidance, and cost tradeoff. Every sentence contributes actionable information 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?

Despite lacking an output schema, the description thoroughly explains the return format and refusal behavior, providing an agent with sufficient context to invoke the tool correctly and interpret results. The use cases and limitations are also clearly stated.

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

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

The input schema has 100% description coverage for all six parameters, which are all aliases for the single question field. The description itself does not add extra parameter semantics, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' and explains its process: routing to tools, filling arguments, fetching data, then extracting the answer only from the tool result. It also distinguishes itself from sibling ask_pipeworx by emphasizing grounded extraction and evidence.

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

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

The description explicitly states when to use the tool ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'), naming the sibling tool and providing a cost rationale.

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

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

The description goes far beyond the annotations (readOnly, openWorld, idempotent, non-destructive). It details fan-out behavior, classifiers, response shapes, resolver contract with match confidence, parent-event extraction, news fallback mechanisms, low-confidence short-circuiting, closed-market handling, wide-spread warnings, and resolution-rule risk. This is rich behavioral context that annotations alone would not 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-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Every sentence provides actionable detail for a complex tool. It is front-loaded with the core purpose and uses clear formatting to avoid wall-of-text confusion.

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 thoroughly explains return shapes, statuses, warnings, and edge cases. It covers input formats, classifiers, examples, resolver contract, parent events, news fallbacks, safety short-circuits, and cancellation rules. For a high-complexity tool, this is exceptionally complete.

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

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

Schema description coverage is 100% (all three parameters have detailed descriptions). The description adds example input values and explains the effect of depth and include_raw in context, but these are already covered in the schema. Baseline 3 is appropriate since the schema carries the weight.

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

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

The description opens with a specific verb+resource+scope: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool from siblings like polymarket_edges or ask_pipeworx by focusing on researching a single bet with fan-out to data packs, not general Q&A or edge 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?

It explicitly states 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', giving clear contexts. It lacks an explicit when-not-to-use or named alternatives, but the usage context is well-defined and the examples provide concrete scenarios.

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

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

The description adds substantial behavioral context beyond the annotations: it discloses data sources (SEC EDGAR/XBRL, FAERS, FDA), handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with pipeworx:// citation URIs. It also notes that it replaces 8–15 sequential lookups. This is rich, non-contradictory information that goes well beyond the readOnly/idempotent hints.

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

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

The description is dense but every sentence earns its place: trigger phrases, explicit preference guidance, data source details for both types, sorting behavior, and output format. It is front-loaded with the most important usage examples and remains well-structured despite its length, which is appropriate given the tool's complexity.

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

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

The description is fully complete for a read-only comparison tool with good annotations and a simple schema. It explains purpose, usage, data sources, edge-case handling (off-calendar fiscal years), sorting, and output structure (paired data + citation URIs). No output schema exists, so the description fully compensates.

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

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

The schema already covers both parameters with descriptions, so the baseline is 3. However, the tool description adds significant meaning beyond the schema by explaining what each type pulls (company: latest 10-K financials; drug: FAERS counts, FDA approvals, trial counts) and how the values are interpreted (e.g., tickers/CIKs for companies, drug names for drugs). This elevates the score above the baseline.

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

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

The description clearly states the tool's purpose with specific verbs and resources: it performs side-by-side comparisons of 2–5 companies or drugs in a single parallel call. It distinguishes itself from sibling tools by explicitly contrasting with sequential single-pack lookups and providing representative trigger phrases like 'compare X and Y' and 'rank these companies.'

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 explicit when-to-use guidance, stating 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also provides concrete examples of query types and specifies the data sources and sorting behavior, making it clear when this tool is the right choice.

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

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

The description goes well beyond the annotations by disclosing depth-tier pricing, parallel tool routing, latency expectations (15-90s), the behavior of returning gaps[] for unanswered facets, contradictions[] scanning, and the guarantee that citations are always fetchable. It also explains semantic excerpting and hop fields, giving deep insight into internals without contradicting the readOnly/idempotent 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 information-dense, with every sentence contributing a distinct behavioral or usage detail. It is front-loaded with the account requirement and key differentiators, though the sheer length and density may slow scanning; still, it remains focused and non-redundant.

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

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

Given the tool's high complexity (parallel routing, depth tiers, citations, contradictions), the description is remarkably complete: it covers return format, latency, limitations for current-news topics, account tiers, and fallback alternatives. No output schema exists, but the description compensates by clearly outlining what the response packet contains.

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?

Although schema coverage is 100%, the description adds substantial meaning: it explains how the 'depth' parameter controls parallel facets and hop strategies (quick=3, standard=5 with gap recovery, thorough=8 with iterative chasing), and clarifies that 'question' accepts broad multi-part queries. This enriches parameter understanding far beyond the schema definitions.

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

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

The description clearly states the tool performs 'grounded multi-source research across Pipeworx's 1452 STRUCTURED data sources' in a single call, explicitly contrasting it with 'open-web search' and sibling tools. It identifies specific use cases like comparing regulatory/financial exposure and researching filings/market pictures, making the purpose highly concrete and 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?

Usage guidance is explicit: it says this tool is 'Best for broad/multi-part questions over structured data' and directs users to ask_pipeworx for single lookups and breaking/current-news topics. It also provides an account-requirement caveat and recommends ask_pipeworx when not signed in, covering both when-to-use and when-not-to-use.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is clear. The description adds valuable behavioral context: it returns top-N relevant tools with names, descriptions, full input schemas, and curated examples, each ready to call directly with no second schema lookup needed. This goes beyond the annotations and informs the agent of the exact output and workflow implications.

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 information-dense and front-loaded with the core purpose in the first sentence. The long list of domains is purposeful for a discovery tool, and the remaining sentences cover usage, return behavior, and when to call. It could be slightly tightened, but every sentence adds value.

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

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

Despite lacking an output schema, the description fully explains what results contain (tool names, descriptions, full schemas, examples) and that they are directly callable. Together with annotations for safety and schema for input, the description covers all needed context for an agent to invoke this tool effectively.

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

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

Schema description coverage is 100%, so the schema fully documents query and aliases including defaults. The description adds no additional parameter-level detail beyond reinforcing that the query is a natural language task description and that results are top-N. Baseline of 3 is appropriate because the schema does the heavy lifting.

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 'Find tools by describing the data or task,' with explicit verbs (browse, search, look up, discover) and a defined resource (tools). It lists the covered domains, making it unambiguous and distinct from sibling tools which are domain-specific operations, not meta-tool discovery.

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 explicit usage guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly distinguishes when to use it versus directly invoking a specific tool.

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

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

Beyond the read-only and idempotent annotations, the description discloses rich behavioral details: parallel fan-out across SEC EDGAR, XBRL, USPTO, news, and GLEIF; patent API sunset with soft-fail; GDELT→GNews fallback; sorting of fundamentals by period_end; and a 'ONE parallel call' performance trait. This adds substantial context not present in 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 example queries and a clear purpose statement. It packs substantial detail into a single paragraph, but the structure is monologic and could benefit from bullets for readability. However, every sentence provides useful information, so it remains efficient for a complex tool.

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

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

With no output schema, the description takes responsibility for explaining return values, and it does so by listing the six output categories (cik/company_name, recent_filings, fundamentals, patents, news, LEI) with relevant limits and sorting. It also notes failure modes (patent soft-fail, news fallback). Minor gaps like exact output shape or error handling prevent a 5, but it is largely 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?

The input schema already covers both parameters with descriptions, including the 'only company supported' note, ticker/CIK format, and the 'names not supported' caveat. The description reiterates these examples but adds no new semantic information beyond what the schema provides, so the baseline 3 for high schema coverage applies.

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

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

The description opens with concrete example queries and clearly states it produces a 'full cross-source profile of a US public company in ONE parallel call.' It enumerates specific sources and output fields, and distinguishes itself from single-pack lookups and sibling tools like resolve_entity. This is a specific verb+resource+scope definition.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' providing a clear when-to-use directive. It also states that names are not supported and instructs to use resolve_entity first, offering a concrete alternative for the unsupported 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 declare destructiveHint and idempotentHint, and the description adds context about what gets deleted (a previously stored memory) and the motivation (clearing sensitive data). No contradiction with annotations; the added context goes beyond the structured hints.

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

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

Two sentences, front-loaded with the core action, and the second sentence provides actionable guidance. Every sentence earns its place with no wasted words or repetition.

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

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

For a simple one-parameter delete operation, the description covers purpose, usage context, and pairing with siblings. Annotations handle safety implications (destructive, idempotent), and no output schema is needed. The tool is fully contextualized.

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 fully describes the 'key' parameter with 100% coverage, so the baseline is 3. The description merely restates 'by key' without adding any additional semantic detail beyond what the schema already provides.

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

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

The description states 'Delete a previously stored memory by key' which clearly identifies the action and resource. It distinguishes from siblings like 'remember' and 'recall' by specifying deletion, making the purpose unambiguous.

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

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

Explicitly states when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also recommends pairing with 'remember' and 'recall,' naming the relevant sibling tools and providing clear alternatives.

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

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

Even though annotations already declare readOnlyHint=true and idempotentHint=true, the description adds process details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also explains the output as a single text blob. This goes beyond the annotations and provides helpful context about tool behavior.

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

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

The description is three sentences, each serving a clear purpose: purpose/outcome, process, and use cases. It is front-loaded with the core action and outcome, contains no redundant or filler content, and is appropriately sized for the tool's complexity.

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

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

Despite having no output schema, the description clearly states the output is a single text blob in standard llms.txt format. Combined with the detailed input schema and annotations, this makes the tool's behavior and expectations clear. Minor missing context (e.g., failure handling or rate limits) would push it to a 5, but it is complete for its moderate complexity.

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

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

The input schema already has 100% coverage with descriptions for both parameters (url and max_links). The tool description adds minimal parameter-specific info, only implying the URL is for the site to summarize. Given the high schema coverage, a baseline of 3 is appropriate; the description does not significantly enhance parameter understanding.

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

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

The description uses a specific verb ('Generate') and a clear resource ('llms.txt file for any URL'), and states the desired outcome (AI crawlers can index the site cleanly). It also distinguishes itself from general web tools by mentioning the standard llms.txt format and specific use cases, setting it apart from 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 ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear guidance on when to use it. However, it does not mention alternatives or exclusions, which would have elevated it to a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds scope (caller's), default active status, and return field details, providing useful context beyond annotations. It does not mention pagination or rate limits, but the tool's simplicity makes this acceptable.

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

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

The description is two sentences with no redundant wording. It front-loads the purpose and return fields, then provides usage guidance, making it concise and well-structured.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers purpose, return values, and usage context. Combined with the rich annotations, it provides sufficient information for an agent to select and invoke the tool correctly.

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

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

The schema fully documents the only parameter (include_inactive) with 100% coverage. The description does not add additional parameter-specific details beyond the schema, but its emphasis on 'active' subscriptions hints at the default behavior. Baseline 3 applies due to high schema coverage.

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

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

The description states a specific action (List) and resource (caller's active subscriptions). It also lists the return fields, making the tool's function concrete and distinguishable from siblings like subscribe and unsubscribe.

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

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

The description provides explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This clearly indicates when to use the tool, though it does not explicitly name alternative tools.

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

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

Annotations are all false, so they provide no safety profile; the description compensates by disclosing the daily rate limit, the claim_token retrieval workflow, and that it is free/non-quota. It stops short of describing data handling/storage, but the workflow is sufficiently transparent for the agent to set expectations.

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 each sentence earns its place: triggers, exclusions, claim_token usage, rate limits, and quota impact are all relevant. It is front-loaded with purpose and usage, with operational details following.

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 still explains what filing returns (claim_token) and how to use it to read resolution status. It also covers edge cases like cross-server feedback, rate limiting, and message content policy, making it complete for this tool's complexity.

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

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

Schema covers 100% of parameters, so baseline is 3; the description adds value by translating feedback scenarios into type categories and showing the claim_token call form ('pipeworx_feedback({claim_token:"pwfb_…"})'). It also instructs agents to reference Pipeworx tools/packs rather than pasting user prompts, which clarifies message construction.

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

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

The description opens with a concrete action ('Tell the Pipeworx team something is broken, missing, or needs to exist') and names the resource. It clearly differentiates from sibling research/ask tools by being the channel for reporting issues and praise about Pipeworx 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?

It supplies explicit triggers: bugs, feature/data gaps, and praise, and maps them to the type enum. It also gives an exclusion rule ('ONLY for tools served by this Pipeworx connection') and directs cross-server issues to the appropriate server.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context about data aggregation (derived from CF analytics-engine), privacy (no PII), response format ((pack, tool, count)), and caching (5min-1h). This goes beyond the annotations, though it could be more explicit about calculation methodology or edge cases.

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

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

The description is well-structured and front-loaded: it opens with the core purpose, then lists outputs, use cases, and technical details in a clear sequence. Numbered use cases and the final data privacy/performance notes are concise and useful; no sentence is wasted.

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

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

For a simple one-parameter tool with no output schema, this description is highly complete: it explains what is returned, how it is computed, privacy guarantees, caching, and the three practical scenarios where an agent might need it. It fully compensates for the lack of an output schema.

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

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

The input schema already provides a full description of the 'window' parameter, including enum values, default, and effect. The tool description itself adds no additional parameter semantics, so the baseline 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 identifies the tool's function with specific verbs and resources: "Returns the top tools, top packs, and total call volume over a recent window." It also sets a clear context ("What other AI agents are calling on Pipeworx right now") that distinguishes it from sibling tools like discover_tools or entity_profile.

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

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

The description explicitly lists three concrete use cases (discovering hot data sources, confirming canonical tools, checking alignment) and explains the trade-off between window lengths. However, it does not explicitly name alternative tools or state when NOT to use this tool, so it falls slightly short of a 5.

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

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

Beyond the read-only annotation, the description discloses important behavioral details: the 3pp partition-check threshold, placeholder filtering with 20% fraction cutoff, semantic similarity anchor (Jaccard ≥0.30), skipped_low_similarity reporting, and the fill-check warning against trading when realizable_edge_pp ≤ 0. 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?

Though long, the description is well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with usage guidance. Every sentence carries meaningful operational detail; density is justified by the tool's complexity.

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

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

The tool has no output schema and only two optional parameters, placing the burden on the description to explain return values and behavior. It covers response structure (opportunities[], partition_check), edge cases, live book pricing, and safety caveats incompletely. The description is fully self-sufficient for invocation and interpretation.

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 substantial meaning: concrete event slug examples, full URL acceptance, cross-event seed question examples, the difference between modes, and behavior like the semantic anchor and partition filter. This far exceeds the schema's minimal parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly defines what the tool does and distinguishes its arbitrage method from siblings like polymarket_edges and polymarket_fill_risk.

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

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

Provides explicit guidance for when to use each invocation mode: no args for trending_scan, 'event' for specific markets (recommended), and 'topic' for cross-event scanning. It also states limitations and alternatives, including 'For custom sizing use polymarket_fill_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?

The description goes far beyond the readOnlyHint/openWorldHint annotations, detailing the data sources (FRED, GDELT), the exact edge calculation (net of slippage), the 24h-move warning, caching behavior (1h at KV level), and diagnostics. It discloses that Fed bets are excluded from ranking, adding significant behavioral context.

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

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

The description is lengthy but well-structured with clear sections (segments, knobs, response top-level, diagnostics). Every sentence provides substantive detail, though it could be more concise. The use of all-caps labels and hierarchical grouping aids readability despite the density.

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

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

Despite lacking an output schema, the description thoroughly documents the response shape (by_segment, fed_candidates/fed_note, _diagnostics), key output fields (edge_pp_net, kelly_fraction, market.liquidity), and the reasoning behind segments. It also explains the diagnostics funnel, making the tool fully comprehensible.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds valuable context beyond the schema, such as the interrelation between min_kelly and min_partition_leg_kelly (parent-level kelly_fraction_half=0) and the rationale for min_liquidity/max_spread_pp as tradeable-edge filters, enhancing parameter understanding.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It explicitly distinguishes itself with 'Built for what should I bet on today' and describes its three output segments, making the purpose specific and unique among 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?

It gives clear use-case context ('discover opportunities without paging hundreds of markets') and explains tradeable-edge knobs and filters. However, it does not explicitly name alternatives or provide when-not-to-use guidance, though the context strongly implies its application.

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

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

The description goes far beyond the readOnlyHint/idempotentHint annotations. It discloses the 60-day snapshot TTL, cache-miss data gaps, daily-close-based decay computations (not intraday), and explains the response structure in detail. This is the kind of behavioral context an agent needs to correctly interpret results.

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 tightly packed with essential information, organized into purpose, Args, RESPONSE, and LIMITS sections. Every sentence adds value, and the front-loaded purpose statement makes it immediately scannable. For a complex telemetry tool with no output schema, this length is fully justified.

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 there is no output schema, the description compensates by fully specifying the response structure (tracked[], expired[], snapshot_dates[]), including field-level details like trend values and decay computation. It also covers operational limitations (TTL, gaps). This is complete for an agent to invoke and interpret the tool effectively.

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

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

Schema description coverage is 100%, and the description repeats the same parameter semantics (defaults, clamps, window family) without adding meaning beyond what the schema already provides. The description adds no new parameter-specific context, so the 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 opens with a specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly answers a concrete question ('how long has this edge existed and is it shrinking?') and distinguishes itself from the sibling 'polymarket_edges' by focusing on temporal tracking rather than current edge values.

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 by contrasting fresh vs. old wide edges, implying use for persistence/decay analysis. However, it does not explicitly name alternatives or state when NOT to use it, relying on implication rather than direct comparison with sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond annotations: it walks the order-book ladder, returns slippage and fill-ability verdicts, and warns that partial basket fills convert an arb into an unhedged directional position. This goes beyond what annotations imply, though it does not mention rate limits or authorization.

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 deliberately structured with mode-specific sections (SINGLE-MARKET vs BASKET) and key terms in caps for scanning. Every sentence adds either mode behavior, return values, or risk context. The density is slightly high, but it avoids fluff and uses whitespace-like capitalization to maintain readability.

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

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

With no output schema present, the description carries full burden for return-value disclosure, and it does so: it lists all key fields per mode (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, etc.) and even includes the output for basket mode (theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs[], forced_directional_risk). It also explains the critical 'why' — why fill risk matters for arb strategies — making the tool 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 high (100% of parameters described), but the description adds crucial per-mode semantics: size_usd is 'max spend' for buys vs 'target proceeds' for sells in single-market mode, but becomes 'settlement notional S (shares per leg)' in basket mode. It also explains the default side logic (auto based on partition sum) and the market/event requirement, which enriches the schema's basic property descriptions.

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

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

The description opens with a specific verb phrase 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' clearly defining the tool as a fill-risk/slippage analyzer. It explicitly contrasts with sibling tools by naming polymarket_arbitrage and polymarket_edges in the usage guidance, distinguishing its role as a pre-trade validation step.

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 when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the two modes (single-market vs basket) and when each is appropriate, plus the consequence of skipping this check (partial fills create unhedged directional positions).

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

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

Despite annotations already indicating read-only and non-destructive behavior, the description adds rich behavioral detail: the compatibility_warning scenarios, temporal_alignment semantics, skipped_cross_type/subtype counters, and the caution that 'most pre-mapped topics return compatibility_warning today.' This goes well beyond annotations and discloses significant tool behavior.

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

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

The description is dense and well-structured. It starts with purpose, then modes, response, safety fields, and a final caveat. Every sentence provides substantive information, and the length is justified given the tool's complexity. 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?

For a complex tool with two modes, safety warnings, and temporal alignment, the description is remarkably complete. It covers response fields (leg-by-leg prices, matched spread, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters), and even discusses limitations. No output schema exists, so the description carries the full burden and succeeds.

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 meaningful value by explaining the two modes, the override behavior of explicit ticker/slug over topic, and the list of valid topic shortcuts. While the schema already documents parameters, the description clarifies parameter relationships and usage scenarios, earning a 4.

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

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

The description clearly states the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It uses a specific resource (cross-venue spread) and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on the two-venue comparison and mentioning participant pool differences.

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 explains two usage modes (topic shortcuts vs explicit ticker/slug) and provides when-to-use context. It also includes when-not guidance, e.g., 'when they aren't [equivalent] the tool says so' and 'aligned:false means spreads are mathematically meaningless across the temporal gap.' However, it does not explicitly name alternative tools or contrast with siblings, so it falls short of a 5.

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

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

Annotations already declare readOnly and non-destructive hints. The description adds context about the rate's significance and return of monthly history, mildly enriching behavior understanding without contradicting annotations.

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

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

Two sentences, front-loaded with an explanatory definition and immediate usage preference. All text is substantive with no padding or redundancy.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers what the rate is, when to use it, and what it returns. Lacks only explicit mention of output format or long-term series limitations, but recent history is noted.

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 fully documents the optional 'recent' parameter with range and default. The description's mention of 'recent monthly history' aligns with the schema but adds little beyond it, 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?

Description clearly states the tool returns the RBA cash rate target and recent monthly history. It distinguishes from web search but does not explicitly contrast with sibling tools like rba_exchange_rates or rba_series, so it falls short of a perfect 5.

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

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

Provides explicit usage preference over web search for queries like 'what is the RBA cash rate'. However, it does not give exclusions or mention when to use alternative RBA tools, making it clear but incomplete on 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 useful behavioral context beyond annotations: it states the rates are 'most recent published', clarifies the quote convention (A$1 = X), and indicates that passing a currency returns historical data. This is valuable supplementary information without contradicting annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and every clause adds value. It lists example currencies, states the usage preference, and explains parameter behavior, all without redundancy or fluff.

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

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

Given the tool's simplicity and strong annotations, the description covers the essential aspects: data source (official RBA), the quote format, the conditional behavior based on currency param, and the recency of data. It does not detail exact return structure, but that is implied given no output schema, and the description is adequate for the tool's scope.

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

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

Input schema covers 100% of parameters with descriptions, so the baseline is 3. The description's mention of 'pass a currency code for that pair's recent history' essentially restates the schema's property description without adding new semantic detail. No additional meaning beyond schema is provided, hence a 3.

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

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

The description clearly identifies the tool as providing official RBA exchange rates for AUD against major currencies, listing specific currency examples. It distinguishes from sibling tools like rba_cash_rate by focusing on exchange rates, and the mention of 'PREFER OVER WEB SEARCH' provides an additional distinguishing context.

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

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

The description explicitly tells agents when to use this tool ('PREFER OVER WEB SEARCH for...'), and explains the two usage modes: without a currency code for all latest rates, and with a currency code for that pair's recent history. This provides clear context 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 indicate read-only, idempotent, non-destructive behavior, so the description doesn't need to repeat those. It adds context beyond annotations by noting 'Returns recent observations' and providing examples of table/series mappings, which helps set expectations for the response. No contradictions with annotations.

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

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

The description is two sentences, front-loaded with the primary action, then provides examples and usage guidance. Every clause serves a purpose—no filler, no repetition of schema content. It is efficiently structured and easy to scan.

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

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

Given the tool's simplicity (3 params, 2 required), the description fully covers what it does, how to use it, when to prefer alternatives, and where to find more information (link to RBA tables). No output schema exists, but the description notes it returns recent observations, which is sufficient for this use case.

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 provides 100% coverage with descriptions and examples for all parameters. The description adds complementary domain context (e.g., 'CPI is g1, monetary aggregates d3') and clarifies the relationship between table and series_id, which enriches the schema's information without redundancy.

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

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

The description uses a specific verb ('Fetch') and clearly identifies the resource ('RBA statistical series') and the method (table id + series id). It also distinguishes itself from sibling tools by explicitly naming rba_cash_rate and rba_exchange_rates as alternatives for common series.

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

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

It explicitly states when to use this tool vs alternatives: 'Use rba_cash_rate / rba_exchange_rates for the common ones.' It also frames itself as an 'escape hatch' for the full catalog, implying it's for less common or specific series not covered by the specialized siblings.

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

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

Beyond the annotations (read-only, idempotent), the description adds key behavioral traits: scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the behavior of omitting the key to list all keys. This enriches understanding without contradicting annotations.

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

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

Three concise sentences, each earning its place: the first defines the action, the second provides use-case context, and the third explains scoping and related tools. No unnecessary verbiage.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is complete. It covers retrieval, listing, scoping, and relationships to sibling tools, leaving no critical gaps for an agent to select and invoke it correctly.

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

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

The schema already covers the 'key' parameter with 100% coverage, so the baseline is 3. The description adds concrete example values (target ticker, address, research notes) that illustrate meaningful usage, slightly elevating the score.

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

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

The description clearly states the tool's dual purpose: retrieving a saved value or listing all saved keys. It uses specific verbs ('Retrieve', 'list') and references the memory store, distinguishing it from sibling tools like remember and forget.

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

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

Explicitly explains when to use the tool: to look up previously saved context without re-deriving it. It also references siblings, instructing to pair with remember for saving and forget for deleting, providing clear context on 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?

The description discloses that setting mark_read:true flags events as read and affects future calls, which is a behavioral trait. However, the annotations declare readOnlyHint:true, which contradicts this documented side effect. Since the description contradicts the annotation, the score is 1 per the rubric.

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

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

The description is four concise sentences, front-loaded with the purpose, and every sentence adds useful information. It includes the key behavior, filtering options, mark_read effect, and an alternative access URL without any fluff.

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

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

For a tool with five optional parameters and no output schema, the description explains what the returned events contain (source, citation_uri, raw payload), how filtering works, and the mark_read side effect. It could mention pagination limits or the exact shape of the payload, but it's adequate for most use cases.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by giving a concrete type example ("sec_8k"), explaining the downstream effect of mark_read, and mentioning the citation_uri and raw payload content. This goes beyond the schema's descriptions.

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

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

The description starts with 'Pull fired events from your subscription feed,' which names a specific action and resource. It clearly distinguishes this tool from siblings like list_subscriptions and recent_changes by focusing on reading fired alerts, not managing subscriptions or tracking changes.

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 states when to use the tool ('Pull fired events...'), how to filter by type and since, and even provides an alternative access method (the same feed at a URL). It doesn't explicitly name alternative tools, but the context is clear and practical.

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

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

Annotations declare readOnly/idempotent, and the description adds substantial behavioral context: fans out to three sources, GDELT preferred with GNews fallback on rate-limit/5xx, USPTO patent source sunset May 2025 with soft-fail, and grouped output structure with citation URIs. No contradiction with annotations.

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

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

The description is a single dense paragraph but every sentence adds value: example queries, source fan-out, parameter format, output shape, and alternative tool. It is long but not wasteful; however, a bulleted breakdown would improve scannability. Still far above average.

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 explicitly states return shape (changes[], total_changes, pipeworx:// URIs). It covers failure modes (GDELT fallback, USPTO sunset), parameter syntax, and source scope. Ideal for a complex multi-source tool with no structured output definition.

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

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

Schema coverage is 100%, but description adds meaningful examples: `since` accepts ISO date or relative shorthand ('7d', '30d', '3m', '1y') with typical usage '30d' or '1m'; `value` can be ticker or zero-padded CIK. This goes beyond the schema's terse descriptions and helps correct invocation.

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

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

The description opens with concrete example queries ('What's new with X', 'latest on Y') and states it's a 'change feed for a company in the last N days/weeks/months in ONE parallel call'. It clearly differentiates from sibling `entity_profile` by contrasting 'static profile' vs. change feed. Specific verb+resource+scope.

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

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

Provides explicit when-to-use context via example intents and window handling. It names the exact alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' Also describes internal fallback logic (GDELT→GNews) and soft-failure for USPTO, 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?

The description discloses behavioral traits beyond annotations: persistence scoped by identifier, retention differences between authenticated and anonymous sessions, and the key-value storage model. This adds valuable context that annotations (readOnlyHint, idempotentHint) do not convey.

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

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

The description is three sentences, each sentence serving a distinct purpose: stating the core function, providing usage context, and explaining storage/retention semantics. No filler or redundant information; it is appropriately concise and well-structured.

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

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

Given the simple two-parameter schema and existing annotations, the description covers all essential aspects: what it does, when to use it, how data is stored, and how it relates to sibling tools. No return value is needed, and no significant gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal parameter-specific meaning beyond the schema; it mentions 'key-value pair' but does not elaborate on the parameters themselves. Thus it doesn't exceed the baseline.

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

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

The description clearly states the tool's function with a specific verb ('Save') and resource ('data the agent will need to reuse later'). It also distinguishes itself from siblings by mentioning 'recall' and 'forget' as companion tools, making the purpose unambiguous.

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

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

The description explicitly specifies when to use the tool: 'Use when you discover something worth carrying forward...' and provides concrete examples. It also names alternatives ('Pair with recall to retrieve later, forget to delete'), giving clear usage guidance.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context beyond that: internal cascading through multiple endpoints, auto-disambiguation for company inputs, and citation URIs in the response. This goes well beyond 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 dense but every sentence contributes value. It begins with user-intent examples, states the core purpose, gives a usage directive, and details supported types. No filler or repetition; the structure is logical and information-rich.

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 for each type (company: ticker, CIK, name, citation URI; drug: RxCUI, ingredient, brand, citation URI). It also covers input flexibility, auto-disambiguation, and internal cascading, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, but the description enriches both parameters significantly. For 'type' it lists supported values with examples, and for 'value' it explains accepted formats (ticker, CIK, name; brand or generic) and mentions auto-disambiguation, which is not in the schema.

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

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

The description clearly states a specific action ('resolve a user-spoken NAME to the canonical/official identifier'), provides concrete example queries, and lists supported entity types. It also distinguishes itself from siblings by explaining it produces IDs that other tools require as input.

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

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

Explicit guidance is given: 'Use FIRST whenever you have a name but need an ID.' The description also implies when not to use it (if you already have the ID) and notes that it replaces 2-3 manual lookups, signaling the intended 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 declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive; the description adds that the tool probes each entity with ai_visibility_check and ranks results, and specifies output fields. This adds behavioral context beyond the annotations without contradicting them.

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

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

The description is three sentences, each contributing: purpose, mechanism (probe with ai_visibility_check and rank), and use case/results. No filler or redundancy; information is front-loaded.

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

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

With no output schema, the description adequately describes the return format (ranked list with score, confidence, signal density). It also covers the tool's purpose, process, and a representative use case. The schema handles parameters, and annotations cover safety, so the description is complete for this complexity.

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

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

The input schema covers all 4 parameters with descriptions (100% coverage), so the description adds no new parameter meaning. It references entities as 'your brand + N competitors' which mirrors the schema's explanation of first entry as subject. Baseline 3 applies.

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

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

The description clearly states a specific action ('Compare AI visibility across multiple entities side-by-side'), specifies the resource (entities' AI presence), and differentiates from sibling tools like ai_visibility_check by emphasizing side-by-side comparison and ranking. It includes concrete output details (ranked list with score/confidence/signal density), making 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?

The description provides a clear use case ('competitive AI-marketing audits') and an example question. It implicitly contrasts with single-entity checks via ai_visibility_check, but does not explicitly state when not to use this tool or name alternatives like compare_entities. Thus it has clear context but no exclusions.

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

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

The description adds significant behavioral context beyond the annotations: it is a composite fan-out call, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed lists timeouts. These details are not available in the annotations and are valuable for the agent to set expectations correctly.

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 every sentence serves a distinct purpose: purpose identification, usage scenarios, return fields, ecosystem limitation, and failure behavior. It is front-loaded with the most important information and remains well-structured, though it could be slightly streamlined without losing clarity.

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

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

With no output schema, the description properly enumerates the summary block fields, per-advisory detail, links, and alternative versions. It also covers edge cases like non-NPM ecosystems and timeouts, ensuring the agent has a complete picture of what to expect and how to handle partial failures. This is comprehensive for the tool's complexity.

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

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

The input schema already provides 100% coverage for both parameters, including scoped package acceptance and version defaulting. The description reinforces this by mentioning 'npm package' and 'version' but does not add new semantic detail beyond what the schema already offers, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose as a composite 'should I add this npm package' check that fans out across deps.dev and bundlephobia. It uses specific verbs like 'scan' and 'check' and enumerates concrete outputs (license, advisories, bundle size, ESM support), making it easily distinguishable from sibling research tools.

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

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

It explicitly states when to use the tool ('is X safe / popular / small' or 'what does adding lodash cost me') and provides an exclusion for non-NPM ecosystems, directing users to deps.dev:version directly. This clear when-to-use and when-not-to-use guidance goes beyond typical descriptions.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses concrete implementation details: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K character cap with truncation flagging, and the return structure (passages with character offsets and similarity scores). This gives the agent a rich behavioral model without contradicting 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 three sentences long and every sentence adds value. It front-loads the core action, then explains when to use it, and finishes with technical specifics. No fluff or repetition; the structure is logical—purpose, usage context, and behavioral detail. This is an exemplary balance of richness and efficiency.

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

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

Given the tool's complexity (3 params, 2 required, no output schema), the description fully covers the context: what the tool does, how the input is used, what output to expect (top-N passages with offsets and scores), and edge-case handling (truncation). It also situates the tool within a larger workflow with ask_pipeworx_grounded, making it self-contained for an agent to decide when and how to invoke it.

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

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

The schema already covers all three parameters with descriptions (100% coverage), so the baseline is 3. However, the description adds semantic context beyond the schema: it clarifies that 'text' is 'the text you already pulled' (e.g., a SEC 10-K body) and provides concrete query examples ('supply-chain risk', 'drug interactions with warfarin'). This elevates the parameter semantics from merely descriptive to practically illustrative.

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

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

The description opens with a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes from sibling tools like ask_pipeworx by emphasizing the 'inside a fetched record' scope and by naming the companion tool ask_pipeworx_grounded. This makes the tool's purpose unambiguous and well-differentiated.

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 explicit guidance: 'Use when the record is too big to cram into the prompt' and explains the benefit ('saves context, returns only the passages that matter'). It also provides an alternative workflow with ask_pipeworx_grounded, showing when to pair this tool rather than use others. This is strong usage guidance beyond just stating the function.

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

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

The description supplements annotations with substantial behavioral context: OAuth requirement, phone verification, 10/day SMS cap, webhook auto-disable after 10 failures, and the one-time return of the webhook signing secret. It also states the return value (subscription id), all consistent with the annotations.

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

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

The description is a long, information-dense paragraph that could be better structured with bullet points or sections. While it is front-loaded with the core purpose, the volume of details may overwhelm, though every sentence provides 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?

For a mutation tool with no output schema, the description covers return value, prerequisites, all supported types, delivery channels, and failure behaviors. It is sufficiently complete for an agent to invoke the tool correctly and understand the results.

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

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

The description adds meaningful examples for each subscription type and clarifies nuances like items code meanings, topic constraints, and the 10/day SMS cap. This goes beyond the schema's already comprehensive parameter descriptions, which cover 100% of parameters.

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

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

The description states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource. It also differentiates from sibling tools like list_subscriptions and unsubscribe by focusing on the creation action.

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 by specifying the need for an OAuth account, excluding anonymous and BYO users, and explaining delivery channel options including pulling via recent_alerts. However, it does not explicitly contrast with sibling tools for listing or unsubscribing subscriptions.

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

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

Annotations already mark the tool as readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral context beyond this by stating that results are drawn from the live catalog of thousands of tools and that each returned question includes the exact tool + argument shape, which informs the agent about output structure and real-time variability. No contradictions exist.

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 dense block that includes example queries, purpose, output details, and usage instructions. Each clause contributes value, though it is somewhat long for a tool with one parameter. It is front-loaded with example queries that immediately signal the tool's purpose, making it efficient despite its length.

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

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

Given the tool has only one optional parameter, no output schema, and comprehensive annotations, the description fully covers what it returns (category-bucketed example questions with tool+argument shapes), when to use it (first when unfamiliar with Pipeworx), and how to parameterize it (with or without topic). It also lists the available categories and the fact that results come from a live catalog, making it complete for an agent's initial exploration.

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

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

The schema already documents the single optional `topic` parameter with 100% coverage, listing allowed values and the behavior when omitted. The description reinforces this with examples but does not add any new semantic meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: it returns category-bucketed example questions with the exact tool and argument shape that answers each, and positions it as the onboarding entry point for an agent that just connected. This distinguishes it from siblings like ask_pipeworx (which likely answers questions directly) and discover_tools (which discovers tools) by focusing on generating question ideas and teaching how to call meta-tools.

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

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

Explicit usage guidance is provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains when to pass a topic versus call with no arguments for the full spread, giving clear context for when to use this tool vs. alternatives.

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

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

Beyond annotations (readOnlyHint false, destructiveHint false), the description adds meaningful context: ownership is enforced, the row is deactivated not deleted, and historical events remain available. This explains auth needs and non-destructive behavior.

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

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

Two sentences, front-loaded with the action, and the second sentence adds necessary constraints without fluff. Every sentence earns its place.

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

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

For a simple one-parameter tool with full schema coverage, rich annotations, and no output schema, the description covers ownership, persistence semantics, and inter-tool relationship with recent_alerts. It is complete.

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

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

Schema description coverage is 100% and already explains the id parameter as a subscription uuid. The description's 'by id' adds no new information 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 and resource. It distinguishes from siblings by focusing on cancellation, and clarifies the deactivation behavior instead of deletion.

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

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

Ownership enforcement is a clear when-to-use guideline: only cancel your own subscriptions. The note about recent_alerts implies that historical events remain accessible there, but it does not explicitly contrast with list_subscriptions or subscribe.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses detailed behavior: the two distinct processing paths (SEC EDGAR+XBRL vs grounded pipeline), the use of exact percent-delta math, the return of a verdict with possible values (confirmed, approximately_correct, refuted, inconclusive, unsupported), actual value with citation, and reasoning. It also explains the tolerance_pct override mechanism, providing significant insight not visible in annotations alone.

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 structured but slightly verbose, opening with a list of natural-language phrasings that could be condensed. However, each subsequent sentence delivers essential information about routing, return values, and efficiency gains. It is not overly long for the complexity it covers, but not as tight as a two-sentence description.

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 moderate complexity, the description fully covers what it does, when to use it, how it works, and what it returns, including a complete list of verdict types. The lack of an output schema is compensated by explicitly listing the return structure. The annotations and parameter details round out the picture, making the tool self-contained for an agent.

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

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

The input schema already has 100% coverage with descriptions and examples for both claim and tolerance_pct. The description adds extra meaning for tolerance_pct, explaining its role as an override and providing context for hallucination detection, while the claim parameter is sufficiently illustrated with examples. This goes beyond the schema's baseline, earning a 4.

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

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

The description clearly identifies the tool's purpose: natural-language claim verification against authoritative sources. It uses specific verbs like 'fact check' and 'verify', and explicitly distinguishes itself from general Q&A tools by describing its specialized routing for company-financial claims via SEC EDGAR+XBRL and fallback to a grounded pipeline for other facts, aligning with sibling tools like ask_pipeworx_grounded.

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 'Use whenever the agent needs to check whether something a user said is factually correct' and provides multiple example user phrasings. It also explains the internal routing logic but does not explicitly mention alternative tools or when not to use it, leaving a small gap in exclusion guidance.

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