Hagstofa Is

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: the default model (Workers AI Llama-3.3-70b free), the BYO key cost implication for Anthropic, and the return structure (per-model {score, confidence, signals, raw_response} + combined view). This is meaningful behavioral disclosure.

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: first states the main action, second covers defaults and API key specifics, third lists return format and use cases. No redundancy or filler—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?

The tool has 4 parameters and no output schema, but the description compensates by stating the return format (per-model object + combined view) and clarifying key behaviors (default model, cost). It also provides use-case context. This is complete enough for an agent to select and invoke the tool correctly.

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

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

The input schema already covers 100% of parameters with descriptions, so baseline is 3. The description enhances this by explaining the default model behavior, the relationship between 'models' and '_apiKey', and the cost implication of using Anthropic. This adds semantic value beyond the schema.

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

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

The description clearly states a specific action: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This distinguishes it from siblings like ask_pipeworx and scan_competitor_ai_presence by focusing on LLM knowledge scoring. The output format is also outlined, adding clarity.

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: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly mention alternative tools or when not to use it, but the use cases give clear context for when to invoke this tool.

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

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

Beyond the annotations (read-only, open-world, idempotent), the description discloses that the tool routes to 5,462 tools, auto-fills arguments, returns stable pipeworx:// citation URIs, is fast, and works on every tier. This adds substantial behavioral context without contradicting any annotation.

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

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

The description is long but well-structured and front-loaded with the 'PREFER OVER WEB SEARCH' directive. It contains useful examples and clearly organized usage guidance. Some redundancy exists between 'START HERE' and the later 'step up only when needed,' but overall it is appropriately sized for a default entry-point router 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?

For a complex tool with no output schema, this description is remarkably complete: it explains the return format (structured answer with citations), covers a broad range of use cases, names alternatives, and addresses special cases like breaking news. The agent has enough context 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 documents all six parameters as aliases for 'question' (100% coverage), so the baseline is 3. The description adds value by specifying what kinds of questions to ask and providing concrete examples, which helps the agent populate the question parameter effectively.

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 routes factual questions to a huge set of verified sources and returns cited structured answers, with a specific verb and resource. It also distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research for different needs.

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 explicit when-to-use guidance (prefer over web search, start here for most questions) and specifies alternatives: ask_pipeworx_grounded for verbatim evidence, deep_research for broad multi-part questions. It even covers breaking-news scenarios, making the usage boundaries very clear.

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

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

Annotations already establish read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: it explains the beta nature, that candidate improvements may be active, that no candidate is currently active (so it currently matches ask_pipeworx), and that results are compared against the stable router. This goes beyond what annotations convey and is genuinely helpful.

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 one paragraph of three sentences, front-loaded with the core identity ('Beta version of ask_pipeworx'). It is mostly efficient, though the final sentence 'Falls back to nothing...' is slightly redundant given the earlier statement that it is a full working router.

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

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

Without an output schema, the description compensates by stating the response shape is identical to ask_pipeworx. It covers current state, usage, and experimental edge, which is sufficient for an agent to decide to use it. It doesn't elaborate on return format, but the reference to the sibling tool mitigates that gap.

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

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

Schema coverage is 100% with all parameters described as aliases for 'question', and the description adds no additional parameter-specific meaning. Per the baseline for high schema coverage, a 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 as a beta variant of ask_pipeworx with the same universal routing function, explicitly distinguishing it from the stable ask_pipeworx sibling. It states the tool's role (routing 5,462 tools) and provides a concrete use case ('want the newest routing'), satisfying the verb+resource specificity.

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 on when to use this tool ('when you want the newest routing') and names the alternative (ask_pipeworx) as the stable router. It does not explicitly state when not to use it, but the implication is clear enough to guide selection.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses critical behavioral traits: refusal reasons (not_in_source, no_tool_match, etc.), the exact return structure with evidence and confidence, and the fact that it uses only tool result content. It even notes the extra LLM call cost, adding valuable context about performance implications. No contradiction with annotations.

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

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

The description is dense and front-loaded with the core concept, then expands into return structure and usage. It contains three long sentences but each sentence carries necessary information. It's slightly verbose but well-organized, earning a 4 rather than a 5.

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 specifies return values (answer, evidence, confidence, source, fetched_at, refusal_reason) and all possible refusal modes. It covers cost, use cases, and alternatives, making the tool self-contained for an agent to invoke correctly. 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%, so the baseline is 3. The schema already describes the single question parameter and its aliases. The description adds general context ('fills arguments') but does not elaborate on the parameters beyond what the schema provides. This is adequate but not enhanced.

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 a specific verb and resource: 'Hallucination-resistant answer mode for high-stakes reads.' It differentiates from siblings by explicitly comparing to 'ask_pipeworx' and describing its unique extraction mechanism ('EXTRACTS the answer using ONLY what the tool result contains'). This is a specific, distinguishable purpose.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives a direct alternative: 'prefer ask_pipeworx for casual lookups' and mentions the cost trade-off ('Costs one extra LLM call'). This clearly defines usage boundaries relative to 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?

Despite annotations indicating read-only and idempotent behavior, the description goes far beyond them by detailing market resolution, classification, fan-out, response contracts, safety mechanisms for low-confidence matches, closed-market handling, wide-spread warnings, and resolution-rule parsing. These behavioral nuances are essential for correct invocation.

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

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

The description is long, but it is well-structured with section headings (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY, etc.) and front-loads the main purpose in the first sentence. Every section adds necessary information for a complex tool; however, it could be more concise while retaining key details.

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

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

The description is exceptionally complete for a tool with no output schema and three parameters. It fully explains response shapes (result.market, result.analysis), resolver contracts, parent event extraction, news fallback behavior, and error statuses (low_confidence_match, market_closed_or_inactive). This leaves little ambiguity 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 schema covers all parameters with high detail (100% coverage), setting a baseline of 3. The description adds extra meaning by giving concrete fan-out examples for different market types (e.g., BTC bet → coingecko + fred) and clarifying include_raw payload sizes (50KB-500KB) and its use cases.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It identifies the specific action (research), resource (Polymarket bet), and data source (Pipeworx). It differentiates from siblings by focusing on bet research rather than arb, edges, or validation.

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 it: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives a specific caution (check resolution-rule risk before sizing sports bets). However, it does not mention explicit exclusions or name alternative tools for other 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 annotations: it specifies data sources (SEC EDGAR/XBRL, FAERS, FDA), the exact metrics pulled per entity type, handling of off-calendar fiscal years, sorting by primary metric, and the return format (paired data + citation URIs). It also states the operation is a single parallel call, which is behaviorally informative. No contradiction with readOnlyHint/idempotentHint.

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

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

The description is moderately long but every sentence carries essential information. It front-loads the core purpose with trigger phrases, then explains the two type-specific behaviors, and ends with output details and efficiency comparison. No filler or redundant statements; the length 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?

Given 2 required parameters, no output schema, and moderate complexity, the description is fully complete. It covers what the tool does, when to use it, what data it retrieves for each type, how results are organized, and what the response contains (paired data + citation URIs). An agent has all necessary context to select and invoke this tool correctly.

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

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

Schema coverage is 100% with both parameters described in the schema, but the description enriches it further. It explains the meaning of 'type' values ('company' pulls latest 10-K revenue, net income, etc.; 'drug' pulls FAERS counts, FDA approvals, trial counts) and clarifies the input format for 'values' with examples like tickers for companies and drug names. It also adds that results are sorted by primary metric, which helps the agent understand how its input affects output.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one call. It distinguishes from siblings like entity_profile by emphasizing parallel comparison and listing trigger phrases such as 'X vs Y' and 'which is bigger'. The resource (companies/drugs) and verb (compare) are 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?

The description explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing direct guidance on when to use this tool. It also names alternatives (sequential lookups) and gives concrete use-case examples: 'which is bigger / better / larger / more profitable', 'rank these companies', 'head to head'. This makes the appropriate usage context unmistakable.

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, openWorldHint, idempotentHint), the description adds substantial behavioral context: account requirements, paid tier for 'thorough,' parallel decomposition into 5,462 tools, return format (findings packet with verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[]), and latency expectations. It explicitly states the tool 'never invented' answers, which is crucial trust information. No contradiction with annotations.

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

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

The description is long but information-dense and well-structured, moving from purpose to usage to behavior. Every sentence adds value, and the dashes help denote comparisons. It's not overly verbose given the tool's complexity, though it could be slightly more scannable with paragraph breaks. Still, it earns 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?

This is a complex tool with no output schema, but the description thoroughly explains what the user gets back (findings packet, citations, gaps, contradictions), how the process works, what to expect latency-wise, and the limitations. It also covers prerequisites (account) and exceptions (paid tier). For the complexity, the description is remarkably complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning beyond the schema: it explains the practical implications of depth choices ('depth:"thorough" needs a paid plan'), the gap-recovery behavior, and the latency differences. This goes beyond what the enum descriptions provide, 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 what the tool does with a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources... in ONE call.' It explicitly distinguishes itself from siblings ('this is NOT open-web search') and compares to ask_pipeworx, making the tool's unique 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?

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data.' It also states when NOT to use it: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx,' naming the alternative tools and the reasoning. This fully covers usage scenarios 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 state readOnlyHint=true and idempotentHint=true. The description adds behavioral context about the return payload: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' It doesn't contradict annotations and enriches understanding of the tool's output.

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: a clear one-sentence purpose, a list of applicable domains, a return-behavior sentence, and a 'Call this FIRST' directive. Every sentence adds value with no fluff, achieving conciseness without losing important details.

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

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

The description is complete for a simple discovery tool. It explains what the tool returns (relevant tools with schemas and examples) and when to use it. There is no output schema, but the description sufficiently covers expected return values. Complexity is low, and the description fills all necessary context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that the query is a natural language task description but doesn't add unique semantics beyond the schema. The limit parameter is not mentioned in the description, but the schema fully documents it, so no additional value needed.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the exact resource (tools) and action (find/discover), and distinguishes itself from siblings by serving as a meta-tool for discovery, not a specific data query tool.

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

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

Explicit usage guidance is provided: '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.' This clearly indicates when to use it and contrasts with getting a direct answer, implying 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 well beyond the annotations, disclosing multi-source fan-out behavior, specific return fields (cik, recent_filings, fundamentals, patents, news, LEI), caveats like 'USPTO PatentsView API sunset May 2025 — soft-fails until reactivated', and fallback logic (GDELT→GNews). It also notes sorting behavior for fundamentals. No contradiction with annotations.

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

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

The description is long but every sentence serves a purpose. It is front-loaded with example queries that help intent matching, then covers scope, return fields, and constraints. The example list could be trimmed, but it directly aids the agent in recognizing when to invoke this 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 only 2 parameters and no output schema, the description fully covers what the tool does, what it returns, and its limitations. It mentions all sources, the structure of results, and special caveats like patent soft-fail and sorting. There is no ambiguity about how to invoke it or what to expect.

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 explicit examples ('AAPL', '0000320193'), specifying that names are not supported, and pointing to resolve_entity for name inputs. These details make the parameter semantics clearer than the schema alone.

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

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

The description clearly states the tool's function: 'full cross-source profile of a US public company in ONE parallel call.' It provides multiple concrete example queries and explicitly distinguishes itself from sibling tools like resolve_entity and compare_entities by stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.'

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

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

Provides explicit usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also tells the agent when NOT to use it: 'names not supported (use resolve_entity first if you only have a name).' This clearly delineates when this tool should be selected 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?

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about what gets deleted (previously stored memory by key) and the purpose (clearing sensitive data), which goes beyond the raw annotation flags. 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 three short, purposeful sentences. It is front-loaded with the primary action, then provides usage context, and concludes with related tools, with zero wasted words.

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

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

For a simple one-parameter delete tool with rich annotations (destructive and idempotent), the description covers purpose, usage timing, and related tools. No output schema exists, so explaining return values is not required, making this complete.

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

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

Schema covers 100% of the single parameter 'key' with the description 'Memory key to delete'. The tool description does not add additional semantics, but the schema already provides sufficient detail, so baseline 3 is appropriate.

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

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

The description clearly states the tool deletes a previously stored memory by key, using the specific verb 'delete' and the resource 'memory'. This distinguishes it from sibling tools like remember and recall, which handle storage and retrieval.

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

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

The description explicitly lists when to use the tool: when context is stale, the task is done, or sensitive data needs clearing. It also mentions pairing with remember and recall, but it does not provide explicit when-not-to-use exclusions or alternative tool names for similar operations.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses the fetch-extract-emit workflow and notes the output is a standard markdown text blob. This adds behavioral context such as network fetching and output format that annotations don't cover.

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

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

The description is four sentences, each earning its place: purpose, process, output, and use cases. It's front-loaded with the main action and avoids 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?

With no output schema, the description compensates by stating the output is a single text blob in llms.txt format. All relevant aspects—purpose, process, usage—are covered for a 2-parameter tool with rich annotations.

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

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

Schema coverage is 100% with descriptions for both parameters (url, max_links). The description adds context that the URL is for any site and that output includes key links, but doesn't significantly enhance parameter understanding beyond the schema.

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

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

The description uses a specific verb 'Generate' with a clear resource 'llms.txt file' and details the extraction process (title/description/key links). It distinguishes itself from sibling tools like ai_visibility_check by focusing on file generation rather than visibility auditing.

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?

Lists concrete 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'), providing clear context on when to use the tool. However, it doesn't explicitly name alternatives like scan_competitor_ai_presence for the auditing 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds return field names (id, type, params, etc.) and clarifies the scope ('caller's active subscriptions'), which enriches the behavioral context beyond the structured annotations.

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

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

The description is two sentences with zero waste. The first sentence states the primary function and return fields; the second gives practical usage guidance. 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?

For a simple read-only list tool with one optional parameter and no output schema, the description covers the essential aspects: what it lists, the returned fields, and when to use it. It doesn't explicitly mention include_inactive, but the schema handles that, so the description is sufficiently 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 schema covers the only parameter (include_inactive) with a clear description (100% coverage). The description does not add extra meaning about the parameter, so baseline 3 is appropriate.

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

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

The description 'List the caller's active subscriptions' uses a specific verb (list) and clearly identifies the resource (subscriptions) and scope (caller's active). It distinguishes from siblings like subscribe/unsubscribe by positioning this as a review tool before adding or canceling.

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 second sentence provides explicit when-to-use guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This clearly ties into sibling tools without naming them directly, but it doesn't mention any exclusions or alternative 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?

Annotations are all false, offering little safety info, so the description must carry the burden. It discloses rate limits ('5 per identifier per day'), that it's free and doesn't count against quota, and that the team reads digests daily, making the impact clear. It also scopes the tool to Pipeworx-served tools only, which is important 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?

Though longer than typical, every sentence adds distinct value: usage conditions, scope restrictions, content requirements, roadmap impact, rate limits, and quota exemption. It's front-loaded with the core purpose and wastes no 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?

The description fully equips an agent to decide whether, when, and how to use this tool. It covers purpose, scope, parameter semantics, constraints, and consequences. No output schema is needed for a simple feedback submission, and the lack of return-value explanation is irrelevant.

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

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

Schema coverage is 100% with descriptions for type, context, and message, so baseline is 3. The description adds valuable guidance on message content ('describe in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and maps type enum values to real scenarios (bug, feature/data_gap, praise). This elevates it above schema alone.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which clearly identifies the resource (Pipeworx team) and the action (submit feedback). This distinguishes it from sibling tools like ask_pipeworx or discover_tools, which are about getting information, not giving feedback.

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

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

The description explicitly states when to use this tool: for bugs, missing features/data gaps, or praise. It also provides a clear exclusion: not for tools from other MCP servers, advising to file with that server instead. This gives the agent strong decision guidance.

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

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

The annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: it explains the data source ('derived from CF analytics-engine'), privacy ('no PII'), output shape ('just (pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). This is rich behavioral disclosure.

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 efficiently structured: a hook sentence, output specifics, three enumerated use cases, and a transparent technical note. Every sentence earns its place, with no redundant filler. Despite moderate length, it remains concise and well-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?

For a tool with one optional parameter and no output schema, the description fully covers the return values (top tools, top packs, total call volume), window options, caching delays, and PII guarantees. It provides enough information for an agent to invoke the tool correctly and interpret results without additional schemas.

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 description for the 'window' parameter already explains its meaning and trade-offs ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The tool description repeats this window information without adding new parameter-level semantics. With 100% schema coverage, 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 purpose: 'What other AI agents are calling on Pipeworx right now' and specifies the output: 'Returns the top tools, top packs, and total call volume over a recent window.' This distinguishes it from siblings like discover_tools by focusing on aggregated usage trends rather than discovery or search.

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

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

The description lists three specific use cases: discovering hot data sources, confirming canonical tool choice, and checking alignment with agent demand. It provides clear context for when to use the tool, but does not explicitly mention alternatives or when not to use it, so it stops short of full exclusion 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 readOnly/openWorld/idempotent/non-destructive, and the description adds behavioral context: threshold of >3pp for signals, Jaccard similarity anchor (≥0.30), placeholder filter (>20% returns null), and fill-check details with realizable_edge_pp ≤ 0 meaning 'do not trade it'. No contradictions with annotations; the description richly supplements 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?

Though long, every sentence earns its place. The description is front-loaded with purpose and mode options, then detailed sub-behaviors, response format, and fill-check caveats. It uses clear separators (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that structure the information without fluff. It 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?

With no output schema, the description fully covers return values: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and partition_check fields. It also explains edge cases like skipped_low_similarity and null signals from placeholder-heavy partitions, plus the fill-check realizable edge warning. This is complete guidance for an agent to invoke and interpret results.

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

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

Schema coverage is 100%, and the description goes far beyond schema descriptions. It provides examples for event ('fed-decision-may-2026') and topic ('Strait of Hormuz traffic returns to normal'), explains internal behavior for each mode, output structure, and even notes that full Polymarket URLs are accepted. This adds substantial meaning beyond the input 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 opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from sibling tools like polymarket_edges (general edges) and polymarket_fill_risk (sizing), and explains three invocation modes (no args, event, topic). This is a precise purpose with no ambiguity.

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: 'Call with NO args for a trending_scan... pass event for... or topic for...'. It recommends event for a specific market and topic for cross-event scanning, and notes that cross-event mode catches patterns single-event misses. It also points to an alternative: 'For custom sizing use polymarket_fill_risk.' This fully satisfies when-to-use and alternative guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description goes well beyond by disclosing model mechanics (lognormal barrier, GDELT ratios), response structure (by_segment, _diagnostics, fed_candidates), and behavioral caveats such as 'your edge may already be in the price' and 'Cached 1h at the KV level.' This is rich, non-redundant 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 long but highly structured, using section breaks for model families, knobs, and response layout. Every sentence carries specific technical detail (e.g., 'tennis 1.02, soccer 1.10, MMA 1.15'). It is front-loaded with the core purpose, so it earns its length, though it is arguably dense enough to be challenging 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?

Given no output schema and 9 parameters, the description compensates thoroughly: it enumerates response top-level keys, per-opportunity fields, diagnostics, caching behavior, and edge cases like Fed bets. It even explains why Fed signal is excluded. This is complete enough for an agent to know what to expect.

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

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

The input schema has 100% coverage, so the baseline is 3. The description adds significant meaning for key parameters, e.g., explaining that min_partition_leg_kelly applies to per-leg Kelly because parent-level kelly_fraction_half is always 0 for partition overrounds, and that min_liquidity/max_spread_pp are 'tradeable-edge filters'. This goes beyond the schema.

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

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

The description uses a specific verb ('Scan top Polymarket markets and return opportunities') and clearly differentiates the tool's scope ('where Pipeworx data disagrees with market price'). It also names three distinct output segments, distinguishing it from generic market tools. The 'what should I bet on today' framing further clarifies its intended purpose.

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

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

The description explicitly states the tool is 'Built for "what should I bet on today"' and that agents can discover opportunities without paging hundreds of markets. It does not explicitly name alternatives, but the detailed knob descriptions and diagnostics indicate when to use these filters. However, there is no explicit 'when not to use' or comparison to sibling tools like polymarket_arbitrage, which leaves some ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds substantial behavioral detail beyond annotations: 60-day snapshot TTL, snapshots written on cache-miss, gaps meaning no scan, decay computed from daily closes (not intraday), and the distinction between tracked vs expired opportunities. No contradictions with annotations.

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

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

The description is long but well-structured with clear sections (purpose, args, RESPONSE, LIMITS). Every sentence carries information and there is no filler. It is denser than necessary for a simple tool, but appropriate for the tool's output complexity and lack of output schema.

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

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

The tool has no output schema, but the description fully explains the response structure: tracked[] with time-series, first_seen, trend, decay_pp_per_day; expired[] with lifespan_days; snapshot_dates[] with gap semantics. It also covers limitations (TTL, daily closes). This is complete for an analyst to invoke and interpret results correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description enriches this by explaining 'window (snapshot family)' which connects to the underlying polymarket_edges concept, and reiterates day limits. This adds marginal meaning beyond the schema, so a 4 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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific analytical question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on the time-series/history aspect 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 gives strong usage context: it explains when this tool adds value ('a fresh wide edge and a 3-week-old wide edge are different trades') and clarifies data caveats (snapshot gaps, TTL). It doesn't explicitly name 'use this instead of X', but the context and sibling names make the appropriate scenario clear.

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

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

Annotations declare readOnly, idempotent, non-destructive. Description adds behavioral context: walks the order-book ladder, returns verdicts (clean|degraded|cannot_fill), and warns about forced_directional_risk and thin legs. No contradiction; description enriches safety understanding without repeating annotation flags.

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?

Long but well-structured with all-caps mode headers and a final usage directive. Every sentence carries information; no filler. The density is justified by the tool's two modes and multiple return values, and the key purpose 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 enumerates all return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also covers parameter constraints and edge-case risks, making it self-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%, but the description adds meaningful semantics beyond the schema: default size_usd 1000, clamp 10–1,000,000, interpretation as max spend on buys vs target proceeds on sells, and basket settlement notional shares-per-leg. It also clarifies the mutual-exclusivity requirement for market vs event, which the schema does not state.

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

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

States a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' Clearly distinguishes single-market vs basket modes and returns specific metrics, differentiating it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly instructs 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why partial fills convert an arb into unhedged directional risk. Names sibling tools directly, providing when-to-use 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description goes well beyond annotations by detailing response structure (leg-by-leg prices, spread[]), safety fields (compatibility_warning conditions), temporal_alignment, and the semantics of skipped_cross_type/subtype counters. It also warns that pre-mapped topics may return warnings, giving the agent a clear picture of edge-case behavior. No contradiction exists between description and 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 highly structured, with clear section labels ('TWO MODES,' 'RESPONSE,' 'SAFETY FIELDS') and dense, purposeful sentences. It earns its length by covering complex behavior, but it could be tightened slightly; for example, the final caveat about pre-mapped topics could be merged with the safety-fields paragraph. Overall, it is efficient 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?

Given that the tool has no output schema, the description carries full responsibility for explaining return values and edge cases. It does so comprehensively: it describes leg-by-leg prices, matched_spreads, compatibility_warning triggers, temporal_alignment, and skipped counters. The description fully prepares an agent to invoke the tool and interpret its result, even for a non-trivial cross-venue spread calculation.

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

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

Schema coverage is 100% with all three parameters described, but the description adds substantial meaning. It explains the two modes, lists allowed topic values, and states that explicit tickers 'Override the topic-mapped Kalshi side' / 'Override the topic-mapped Polymarket side.' This clarifies the parameter relationships and usage patterns beyond the schema's simple field 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 begins with a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly identifies the tool's function and differentiates from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison. It also distinguishes two modes (topic shortcuts and explicit tickers), further clarifying its purpose.

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

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

The description explains when to use the tool and its modes: 'TWO MODES: (1) `topic` — 10 pre-mapped macro shortcuts... (2) explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings.' It also provides clear guidance on expectations with 'Real cross-venue spreads are rarer than the macro-shortcut list suggests—most pre-mapped topics return compatibility_warning today.' However, it does not explicitly name alternative tools or state 'when not to use this tool,' 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 read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context by warning about PxWeb request size limits and the requirement of the .px suffix in the path. This goes beyond annotations without contradicting them.

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

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

The description is two sentences, front-loaded with the action, and every word adds value. It efficiently packs the core purpose, parameter hints, and a critical usage warning without any padding.

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 data-fetch tool with strong annotations and a schema example, it is largely complete. The description covers the key constraints (request size, .px suffix) but does not mention the return format; however, the schema example shows response format json-stat2, so the agent can infer it.

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

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

Schema description coverage is 50%, but the description compensates by identifying 'body is a PxWeb query object' and 'path includes the .px suffix'. Combined with the schema example showing body structure, it provides enough semantic clarity for both parameters, though it could offer more detail on the query object format.

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

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

The description states the action clearly: 'Pull data from a table', and specifies the resource (path with .px suffix) and the query object body. This distinguishes it from sibling tools like table_meta (metadata) and search_within by focusing on data extraction from a PxWeb table.

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 provides actionable usage guidance: 'PxWeb limits request size — filter dimensions to keep the cell count small.' This tells the agent how to construct requests effectively, though it doesn't explicitly mention when to use this tool over others. It gives context but no exclusions or 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=true and idempotentHint=true, so the safety profile is known. The description adds valuable context: scoping to identifier (anonymous IP, BYO key hash, account ID) and the list-all behavior when the key is omitted. This goes 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?

Three sentences, each earning its place: action and modes, usage rationale with examples, and scoping details. Front-loaded with the primary verb and tightly written with no redundant words.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete. It covers the operation, the meaning of the parameter, scoping, and relationships to sibling tools, while annotations handle the safety and idempotency aspects.

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

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

Schema description coverage is 100%, and the schema already explains the key parameter and omission behavior. The description reinforces this but adds examples of what keys might contain (target ticker, address, research notes), which helps conceptual understanding but doesn't introduce new parameter semantics beyond the schema.

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

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

The description uses a specific verb ('Retrieve') and clearly identifies the resource (values saved via remember) with two modes: retrieving a specific key or listing all saved keys. It distinguishes itself from sibling tools remember and forget by explicitly mentioning them as counterparts.

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

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

Provides clear usage context: 'Use to look up context the agent stored earlier' and gives concrete examples. It mentions pairing with remember and forget, implying when to use each, but does not explicitly state when not to use this tool or name alternatives beyond the sibling pairing.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, lowering the bar. The description adds valuable context beyond the annotations: return payload details (source, citation_uri, raw event), the mark_read side effect ('flag returned events read so the next call only shows newer ones'), and an alternative access method. This enriches understanding of 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?

Three sentences, front-loaded with the main purpose, each providing distinct value: what the tool returns, how to filter, and note about polling/alternative access. No redundant text or filler.

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 read-only tool with 5 optional parameters, no output schema, and strong annotations, the description covers all key aspects: return format, filtering, mark_read side effect, polling behavior, and an alternative access URL. It is self-sufficient without needing additional detail.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning: a concrete type example ('sec_8k'), the relationship between since and fired_at, and a deeper explanation of mark_read's effect on subsequent calls. This goes beyond the schema's field 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 uses a specific verb ('Pull fired events from your subscription feed') that clearly identifies the resource and action. It distinguishes itself from siblings like list_subscriptions (which lists subscriptions) and recent_changes (which likely tracks changes, not alerts).

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 context for usage: 'Polls work fine' suggests it's suitable for repeated polling, and the alternative HTTP endpoint ('the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards') tells when to use an external method instead. It doesn't explicitly name sibling tools as alternatives, but the guidance is sufficient.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses substantial behavioral traits: fan-out to multiple sources, GDELT preference with GNews fallback on rate-limit/5xx, USPTO sunset causing soft-fail, and the return format (structured changes[] grouped by source + total_changes + citation URIs). This is exactly the kind of context that enables correct invocation and expectation setting.

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 well-structured: it leads with purpose, then sources, parameters, return format, and alternatives. However, the opening six example queries are somewhat redundant ('What's new with X' / 'latest on Y' / ...). Each sentence generally earns its place, but slight trimming would make it even more concise.

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

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

For a read-only, multi-source aggregation tool with no output schema, the description is complete. It explains the time-window semantics, fallback logic, source failures, parameter formats, and return structure. The agent has everything needed to use the tool correctly and interpret results. The alternative mention to entity_profile completes the decision context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing concrete examples for `since` (ISO date vs. relative forms) and a recommendation ('Use "30d" or "1m" for typical monitoring'). It also clarifies that `value` accepts ticker or zero-padded CIK, though the schema already states that. This goes beyond the bare 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 opens with concrete example queries ('What's new with X', 'latest on Y') and then defines the tool as a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' This is a specific verb+resource+scope, and it explicitly distinguishes from the sibling 'entity_profile' by noting what that tool covers. No ambiguity remains about what this tool does.

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 signals (dynamic changes over a window) and provides a clear alternative: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It also details fallback behavior (GDELT→GNews) and failure modes (USPTO soft-fails), helping the agent decide when to invoke 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?

Annotations already declare non-readonly, idempotent, non-destructive behavior. The description adds valuable context beyond annotations: key-value pair scoped by agent identifier, persistence behavior ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'), and pairing with recall/forget. This adds meaningful behavioral disclosure 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 three sentences, each earning its place: purpose, usage examples, and persistence/companion notes. No redundant or filler content; information is front-loaded and scannable.

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 2-parameter tool with 100% schema coverage, no output schema, and annotations covering safety, the description is complete. It covers purpose, usage, persistence, and relationships to sibling tools, giving an agent everything needed 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?

Schema description coverage is 100% for both parameters (key and value), with rich descriptions including examples. The tool description itself adds only the generic phrase 'key-value pair', which is already evident from the schema. Therefore, the description does not need to compensate, and 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: 'Save data the agent will need to reuse later' and immediately clarifies scope ('across this conversation or across sessions'). It also distinguishes from sibling tools by naming recall and forget as companions for retrieval and deletion, making the tool's unique role clear.

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

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

Provides explicit guidance on when to use: 'Use when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject)'. It also gives explicit pairing guidance with recall and forget, which are sibling tools, showing the correct usage context. This goes beyond vague context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds valuable context: it cascades through several internal lookup endpoints, auto-disambiguates input, and returns specific fields with citation URIs. This goes beyond the annotations and helps set expectations for an agent.

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 bit long but every sentence is informative: examples, purpose, usage directive, type details, and internal behavior. It's front-loaded with the purpose and includes concrete examples. The structure is clear and not 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 has no output schema, the description does a solid job listing return components (ticker, CIK, RxCUI, citation URIs) and covering input variants, use case, and internal behavior. It is largely complete for an entity-resolution tool, though it does not explicitly describe error cases or ambiguity handling beyond 'auto-disambiguated'.

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 extra semantics by elaborating acceptable input forms for each type (e.g., ticker, CIK, or name for company; brand or generic for drug) and mentioning auto-disambiguation, which enriches the parameter meaning beyond the schema.

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

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

The description clearly states the tool resolves a user-spoken NAME to the canonical/official identifier required by other tools, using specific verbs like 'resolve' and 'look up'. It distinguishes itself from siblings by focusing on name-to-ID conversion and explicitly listing supported types (company, drug) and what each returns.

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: 'Use FIRST whenever you have a name but need an ID.' It also notes that it replaces 2-3 manual lookups. However, it does not mention when not to use it or name alternative tools, so it falls short of full exclusion/alternative coverage.

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 behavior. The description adds useful behavioral context: it probes each entity via ai_visibility_check, ranks results, and returns a structured list. It does not contradict annotations and provides transparency about the orchestration and return format.

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

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

Three sentences with zero filler. The first sentence states the core action, the second explains the method and output, and the third gives a concrete use case. Every sentence earns its place and the structure is front-loaded.

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

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

Given no output schema, the description informs the agent that results include a ranked list with score, confidence, and signal density per entity. It also covers input context and the use of ai_visibility_check. It could mention error cases or the number of calls made, but the provided context is sufficient for correct selection and invocation.

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

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

Schema description coverage is 100%, with detailed parameter descriptions for entities, models, _apiKey, and context. The description adds little beyond the schema, only reinforcing the entity roles and the purpose of models. Baseline 3 is appropriate since the schema carries the full explanatory burden.

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

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

The description uses specific language: 'Compare AI visibility across multiple entities side-by-side', explicitly states it probes with ai_visibility_check, ranks by score, and identifies which entity is most/least recognized. This clearly distinguishes it from the single-entity sibling ai_visibility_check and the generic compare_entities.

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

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

It provides a clear use case ('competitive AI-marketing audits') and implies multi-entity comparisons ('your brand + N competitors'). However, it does not explicitly state when to use this instead of alternatives or list exclusions, 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?

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses the composite fan-out architecture, the exact return fields, partial failure degradation, and the 5-30s latency caveat for bundlephobia's first measurement. It mentions the sources_failed field, which is not in the schema or annotations. No contradiction with annotations.

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

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

The description is long but well-structured and every sentence adds value: it covers purpose, usage, return structure, ecosystem constraints, and failure behavior in a logical order. It is front-loaded with the main purpose and avoids repetition or filler.

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

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

With no output schema, the description fully carries the burden of explaining return values—it enumerates the summary block fields, advisory details, links, and alternative versions. It also covers operational expectations like execution time, partial failures, and ecosystem boundaries, making it highly complete for a composite tool.

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

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

The input schema provides 100% coverage with clear descriptions for both 'package' and 'version', including types and default behavior. The description adds no new parameter semantics beyond the schema; it only provides examples and context. Baseline 3 is appropriate as 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 opens with a specific and clear statement: 'Composite "should I add this npm package to my project" check in ONE call' and names the exact data sources (deps.dev and bundlephobia). This distinguishes it from sibling tools that address unrelated domains like Polymarket, research, or entity resolution.

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: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives an important exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', pointing to an alternative for non-NPM packages.

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 several behavioral specifics beyond the annotations: it returns character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char overlapping windows, and enforces a 200K char cap with truncation flagged. These details give the agent an accurate mental model of what to expect, and they do not contradict the readOnlyHint or idempotentHint.

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

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

The description is front-loaded with the core action in the first sentence, and every subsequent sentence contributes distinct information: output format, use case, integration with a sibling, and technical details. It is dense but not bloated, and remains readable for an AI agent.

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

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

Given the tool's complexity (semantic search, overlapping windows, offsets), the description covers the essential behavioral contract: inputs, outputs (passages with offsets and similarity scores), limits, and edge cases (truncation). There is no output schema, so the description's explicit return description fills the gap.

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

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

The schema already describes all three parameters (text, query, limit) with 100% coverage, so the baseline is 3. The description adds value by giving concrete examples of queries and explaining the practical role of the text parameter (e.g., 'SEC 10-K body, an article, a long tool result'). It also clarifies that limit controls the top-N passages, reinforcing 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 opens with a clear, specific verb+resource: 'Semantic search INSIDE a fetched record,' which immediately conveys the tool's unique scope. It distinguishes itself from siblings by emphasizing that it operates on already-fetched text rather than global or database-backed search. Examples like SEC 10-K body further cement its purpose.

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

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

The description explicitly states when to use the tool: 'Use when the record is too big to cram into the prompt.' It also names a sibling tool (ask_pipeworx_grounded) and describes a complementary workflow, contrasting fetching with grounding. This gives clear guidance on choosing search_within 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context beyond annotations: root behavior, node types ('l' for folders, 't' for tables with ids ending in '.px'), and path traversal semantics. This gives the agent concrete expectations for output structure.

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

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

The description is two sentences long, front-loaded with purpose and followed by behavioral detail. Every sentence contributes meaningful information without any filler or redundancy.

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

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

The tool is simple (one optional parameter, strong annotations, no nested output schema). The description covers root vs sub-path behavior, node types, and id suffix conventions, which is sufficient for an agent to understand inputs and expected outputs fully.

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

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

The input schema fully documents the single optional 'path' parameter with a description and example. The tool description does not add additional parameter-specific semantics beyond what the schema already provides, 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 uses a specific verb 'Navigate' and clearly identifies the resource as 'database/subject tree'. It distinguishes from siblings like query_table and table_meta by focusing on tree traversal and listing node types (databases, folders, tables).

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

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

The description implies when to use the tool: when exploring the hierarchical subject tree, with root listing databases and sub-paths listing folders/tables. It does not explicitly exclude other tools, but the navigation context is clear enough for an agent to select it appropriately.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, which align with the 'Create' action. The description adds valuable context beyond annotations: OAuth account requirement, anonymous/BYO limitation, SMS verification and 10/day cap, and always-on feed with pull methods. This significantly enriches the agent's understanding of operational constraints and side effects.

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 that front-loads the core action and then layers in necessary detail. Every sentence contributes useful information, from the subscription types with examples to delivery channels. There is no redundancy or filler, making it highly efficient for agent consumption.

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

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

Given the tool has no output schema, the description states the key return value ('Returns the new subscription id') but omits potential error cases or full response structure. It covers authentication, types, and delivery channels thoroughly, and the schema fills in webhook details. The description is complete enough for a create operation, though mention of webhook secret retrieval would be a minor enhancement.

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 base score is 3. The description elevates it by providing concrete examples for type-specific params, such as items:["5.02"] meaning officer change and topic:"fed" for Polymarket, which are not fully explained in the schema. It also clarifies delivery channel semantics like SMS verification and the 10/day cap, adding meaning beyond raw parameter 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 begins with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly states the function, returns the new subscription id, and differentiates from siblings like list_subscriptions and unsubscribe by focusing on creation. The supported types and delivery channels are explicitly mentioned, leaving no ambiguity about what the tool does.

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, including required OAuth account and types of subscriptions. It implies alternatives by noting that the feed can be pulled via recent_alerts or GET registry.pipeworx.io/alerts.json, but it does not explicitly name sibling tools like list_subscriptions or unsubscribe for managing subscriptions. This is clear context without explicit 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds context beyond that: it explains this tool draws from the live catalog of thousands of tools, returns example questions with tool shapes, and is an onboarding entry point. It doesn't conflict with annotations, but also doesn't disclose any unexpected behavior other than the scope of returned data.

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 that front-loads example user questions and immediately states the tool's role. While it is long, every segment serves a purpose: explaining the return format, category list, argument behavior, and guidance on when to use it. It avoids wasted words, but could be split into clearer bullets for 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?

Given there is no output schema, the description does a good job of describing what the tool returns (categorized example questions with tool and argument shape). It covers both invocation modes (no args vs topic) and situates the tool within the broader suite. The description is complete enough for an agent to decide when and how to call it.

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

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

Schema coverage is 100% and the schema already documents the topic parameter with its allowed values. The description adds minimal extra meaning: examples of topic values (finance, pharma, betting) and clarifies that omitting topic yields a cross-category spread. This is useful but not a major leap beyond the schema.

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

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

The description uses specific verbs ('returns', 'call') and identifies the resource ('category-bucketed example questions') and the exact tool purpose (onboarding entry point). It clearly distinguishes itself from siblings by positioning as the first thing to use when you don't know what Pipeworx can do.

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

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

Explicitly states when to use: '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 names alternatives (ask_pipeworx, entity_profile, compare_entities) and gives direction on optional argument behavior ('Call with no arguments for the full spread, or pass topic').

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 this as a safe read-only, idempotent operation. The description adds one important behavioral constraint (the '.px' suffix requirement) but doesn't disclose potential errors or response format. Given strong annotation coverage, a score of 3 is appropriate.

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, tightly written sentence that communicates both the tool's purpose and a key usage constraint. Every word earns its place with no 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?

For a simple one-parameter tool with strong annotations and no output schema, the description covers the essential purpose and a crucial path constraint. It doesn't describe the return format in detail, but given the low complexity, the description is largely complete for an agent to invoke the tool correctly.

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

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

The schema already provides 100% parameter coverage with an example. The description adds extra semantic value by explicitly stating the '.px' suffix requirement, which is not explicitly mentioned in the schema parameter description beyond the example. This enriches the single parameter's meaning.

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

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

The description states the tool provides 'Table definition (dimensions, valid values)', which clearly indicates the resource and content type. It distinguishes from sibling tools like query_table, though it lacks an explicit verb like 'get' or 'retrieve'.

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

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

The description implies usage for obtaining table metadata and includes a clear prerequisite that the path must end with '.px'. However, it doesn't explicitly contrast with alternatives like query_table or search_within, so the when-to-use guidance is only partially present.

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=false, destructiveHint=false), the description discloses that the subscription is deactivated rather than deleted, that ownership is enforced, and that historical events stay available via recent_alerts. This adds meaningful behavioral context that annotations alone do 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 two sentences, concise, and front-loaded with the primary action. Every sentence earns its place by providing essential context (ownership and soft-delete behavior) without unnecessary detail.

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 single-parameter mutation with no output schema, the description fully covers the action, the ownership rule, and the side effect (soft delete with history preserved). It also references recent_alerts to connect the historical events availability, 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?

The only parameter id is fully described in the input schema as 'Subscription id (uuid) returned by subscribe.' with 100% coverage. The description adds no additional parameter semantics beyond the phrase 'by id,' so the schema carries the burden, resulting in the baseline score of 3.

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

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

The description begins with 'Cancel a subscription by id,' which clearly identifies the verb (Cancel), resource (subscription), and method (by id). It distinguishes itself from sibling tools like subscribe and list_subscriptions by focusing on the cancellation action and the soft-delete behavior.

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

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

It states that ownership is enforced (you can only cancel your own subscriptions), which sets a clear usage constraint. It also notes the consequence of cancellation (row deactivated, historical events remain). However, it does not explicitly name alternatives or describe when not to use it, so it stops 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 mark the tool as read-only, open-world, and idempotent. The description goes beyond that by explaining the two execution paths (structured XBRL vs. grounded pipeline), the precise percent-delta math, the return verdict types, and the inclusion of verbatim citations. This gives the agent a clear model of what happens internally and what to expect in the response, though it does not cover potential failure modes or rate limits.

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, starting with trigger phrases, then purpose, routing, output, and value proposition. Every sentence contributes useful information. It could be slightly tighter (e.g., 'grounded pipeline' is mentioned twice), but it remains appropriately concise 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?

Given the lack of an output schema, the description does well to enumerate the possible verdicts, the actual value with citation, and reasoning. It also explains the two routing scenarios based on claim type. Minor gaps include not explaining what the 'grounded pipeline' concretely does or how 'approximately_correct' is calibrated beyond tolerance_pct, but overall it provides sufficient context 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?

Schema coverage is 100% for both parameters, so the baseline is 3. The description adds significant meaning beyond the schema: it clarifies the default tolerance behavior ('implied by wording, capped at 5'), gives a practical use case for setting tolerance_pct to 1–2 for hallucination detection, and provides concrete examples for the claim parameter. This is a strong enhancement over the raw schema.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It includes specific trigger phrases ('fact check', 'verify the claim that...'), which aids the agent in recognizing when to invoke it. It also distinguishes itself from siblings by detailing the structured SEC EDGAR fast path for company-financial claims versus the grounded pipeline for all other factual claims.

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 an explicit when-to-use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also implies when-not-to-use by routing non-factual or non-verifiable claims away, and explains that it replaces 4–6 sequential calls. However, it does not explicitly name alternative tools or state exclusions, so it stops short of a full 5.

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