Hdx

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by detailing that the default model is free (Workers AI), a paid Anthropic option requires a BYO API key, and the return structure includes per-model details. No contradictions.

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

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

The description is three sentences with no fluff. The first sentence front-loads the core purpose and result. Every sentence adds essential information.

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

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

Given no output schema, the description sufficiently outlines return values ('per-model {score, confidence, signals, raw_response} + a combined view'). Parameter documentation is complete (4 params, 1 required, 100% schema coverage). The tool is moderate complexity, and the description covers all necessary 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 coverage is 100%, baseline 3. The description adds contextual examples for 'entity' (e.g., 'Pipeworx'), clarifies the 'models' parameter values and defaults, explains '_apiKey' usage, and provides a usage hint for 'context'. This enhances understanding beyond the schema.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility. It uses a specific verb ('probe') and resource ('LLMs for visibility'), and it distinguishes itself from sibling tools like 'ask_pipeworx' or 'compare_entities' by focusing on AI visibility audits.

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

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

The description explicitly states use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It doesn't explicitly mention when not to use or name alternative tools, but the context is clear and sufficient for an agent to decide.

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

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

Annotations already cover readOnly, openWorld, idempotent, and non-destructive traits. The description adds valuable behavioral context: routing to 5,743 tools, returning structured answers with pipeworx:// citation URIs, working on all tiers, and being fast. It doesn't contradict annotations and provides useful operational details beyond the safety profile.

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

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

The description is longer than average but well-structured: it front-loads the key directive, then explains routing, gives examples, and specifies when to use alternatives. Every section earns its place, though it could be trimmed slightly without losing value. It's organized and skimmable.

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

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

For a complex routing tool with no output schema, the description covers all essential context: what it does, when to use it, how it differs from alternatives, what it returns (structured answer with citations), and even performance characteristics. An agent has enough information to call it correctly and know what to expect, with no significant gaps.

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

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

The schema has full coverage (100%) for the parameters — all are aliases for 'question' with descriptions. The description only reiterates that the input is a natural language question, which the schema already states. It adds no new parameter-level meaning, so the baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: answering factual questions by routing to a large pool of tools and returning structured answers with citation URIs. It explicitly differentiates itself from siblings like ask_pipeworx_grounded and deep_research, and even from web search, making the tool's role unmistakable.

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

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

Provides explicit when-to-use and when-not-to-use guidance. It opens with 'PREFER OVER WEB SEARCH', lists trigger phrases, gives examples, and instructs to 'START HERE'. It also names alternatives (ask_pipeworx_grounded for grounded answers, deep_research for multi-part queries) and the conditions to step up. This is exemplary usage guidance.

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

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

Annotations already declare readOnly and idempotent hints, but the description adds important behavioral context: candidate routing improvements are live only when under test, none is active currently, the tool is a full working router, and there is no fallback. This goes well beyond the annotations and clarifies the experimental nature.

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

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

The description is detailed but organized, front-loading the core beta identity and then adding current status, usage, and fallback behavior. It is slightly wordy in places, such as the date of the last retirement, but each sentence contributes to a complete understanding.

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

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

For a tool with one required parameter, rich annotations, and no output schema, the description is remarkably complete: it explains current behavior, exact parity with ask_pipeworx, the experimental comparison purpose, and explicitly states there is no fallback. An agent has enough to determine 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 covers all six parameters with 100% coverage, documenting each as an alias for question. The description adds little beyond saying 'same arguments' and identifying the tool as a router; it does not enrich parameter semantics further. 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 identifies this as the beta version of ask_pipeworx, a universal router with identical arguments and response shape, and explicitly distinguishes it from the stable ask_pipeworx. It states the tool's scope and current exact behavior, leaving no ambiguity about what it does or which sibling it relates to.

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

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

The description gives explicit usage context: use it exactly like ask_pipeworx when you want the newest routing, and mentions comparison against the stable router. It clearly points to the alternative (ask_pipeworx) but does not explicitly state when NOT to use this beta version, such as for production-critical tasks, so it falls short of a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds critical behavioral context beyond that: it returns {answer, evidence, confidence, ...} on success and detailed refusal_reason values on failure, and it discloses the cost of an extra LLM call. No contradiction with annotations; instead it complements them with operational details.

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

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

The description is dense but every sentence conveys essential information: what it does, when to use, the return contract, refusal reasons, and cost trade-off. It is longer than average but justified by the richness of the behavior. Could be slightly trimmed, but it's well-structured and front-loaded.

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

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

For a tool with no output schema, the description fully specifies the success and failure return shapes, enumerates refusal reasons, names the alternative, and gives usage guidance. Nothing a caller needs to decide or interpret is missing.

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 schema already documents the 'question' parameter and its aliases. The description adds no parameter-specific semantics beyond the schema, which aligns with the baseline of 3 for fully documented schemas.

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

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

The description states a clear purpose: a grounded, hallucination-resistant answer mode that extracts answers solely from tool results, with explicit refusal behavior. It distinguishes itself from the sibling ask_pipeworx by emphasizing the evidence/refusal contract, making selection unambiguous.

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

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

Explicitly states when to use (high-stakes reads where answers will be quoted or acted on) and when not (casual lookups, prefer ask_pipeworx). Names the alternative and gives the cost trade-off (one extra LLM call). This is model 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 indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context beyond these: market resolution confidence levels (match confidence, score, alternatives), parent event extraction, news fields with fallback/retry logic, safety short-circuits for low-confidence matches, closed markets, wide spreads, and resolution-rule risk parsing. No contradictions with annotations.

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

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

The description is very long and dense, covering many details. It is well-organized with clear sections (classifiers, fan-out examples, response shapes, resolver contract, etc.) and front-loaded with the core purpose. However, the length might overwhelm an agent; some details could be streamlined or split into a separate guide, but the structure is logical and 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?

Given the tool's complexity, three input parameters, and no output schema, the description is remarkably complete. It covers input formats, behavior for different bet types, response structure (market, analysis, evidence), error states (low confidence, closed markets, wide spreads), safety warnings, and resolution-rule risks. All essential information for correct agent invocation is present.

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. The description adds significant meaning: the 'market' parameter can be a slug, URL, or question text; 'depth' options are clarified as quick vs thorough with source counts; 'include_raw' is explained with size implications (summarized vs full payloads) and use cases. This goes well beyond schema definitions.

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

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

The description clearly states the tool's purpose: research a Polymarket bet by pulling Pipeworx data, resolving the market, classifying, fanning out to data packs, and returning evidence with comparison. It uses specific verbs ('Research', 'pull', 'resolve', 'classify', 'fan out', 'return') and is easily distinguished from sibling tools like polymarket_arbitrage or polymarket_edges, which have different objectives.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It provides multiple examples and outlines behavior for specific scenarios. While it doesn't explicitly state when not to use it, the context makes it clear, and sibling tools cover alternative use cases.

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

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

Discloses key behavioral traits beyond annotations: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, return format (paired data + citation URIs), and sorting by primary metric. Annotations confirm read-only, open-world, idempotent, non-destructive nature.

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

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

The description is a single paragraph but front-loads trigger phrases and usage preference. Every sentence adds value; the structure is clear, though it could be broken into shorter sentences for easier scanning.

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

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

The tool has 2 parameters with full schema coverage and no output schema. The description explains the return format (paired data + citation URIs) and replaces significant manual effort (8–15 sequential lookups), making it fully self-contained for the 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?

Schema coverage is 100% with descriptions from the input schema. The description adds significant meaning: explains what financials are pulled for companies (revenue, net income, cash, debt) and what data for drugs (adverse-event counts, FDA approvals, trials), and constrains array size (2–5) and ticker/name 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 uses specific verbs ('compare', 'side-by-side comparison') and resources ('companies or drugs') with clear trigger phrases. It distinguishes from sibling tools like 'entity_profile' by emphasizing parallel lookups over sequential single-pack lookups.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear guidance on when to use. However, it does not explicitly describe when not to use the tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds the important detail that each resource has download URLs and that HDX does not expose a keyless row query. This provides context beyond annotations without contradiction.

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

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

Two sentences with no fluff. The first sentence defines the main action, and the second adds crucial context for using the output. Perfectly 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 the single parameter, high schema coverage, and clear explanation of the output (including how to read data files), the description is fully 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?

Schema coverage is 100% with a clear description for the 'id' parameter. The description adds no further parameter-level meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns a full dataset record by id or slug, including resources, and distinguishes it from search tools by specifying that it contains download URLs. The verb 'returns' and resource 'full dataset record' are specific.

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

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

The description implies usage when needing full dataset metadata and download URLs, but does not explicitly state when to use this tool versus alternatives like search_datasets. No when-not or comparative 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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds substantial behavioral context beyond that: it explains the parallel decomposition, the return packet structure (gaps[], contradictions[], hop, citation_uri), the guarantee that citations are always fetchable, the excerpting behavior, and expected latency. It also clarifies that 'standard' and 'thorough' include a contradiction scan. This fully discloses the tool's behavior 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 each sentence carries load-bearing information: account requirement, alternative tool, core function, not open-web, decomposition, return packet, gaps[], when to use/don't use, second-hop behavior, contradictions, citation guarantee, excerpting, and latency. There is minor redundancy (e.g., 'not open-web' is mentioned twice, 'one call' repeated), but the structure is front-loaded with the most critical operational facts (account) and the density is justified by the tool's complexity. It earns a 4, not a 5, due to some verbose repetition.

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

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

For a complex tool with no output schema, the description covers everything an agent needs to call it correctly: authentication prerequisite, alternative routing, expected latency, return format details (evidence, confidence, source, fetched_at, citations, gaps, contradictions, hop), and how depth affects iterations. It also explains when the tool will yield empty results (current-news topics). No important behavior is left undocumented within the scope of a tool description.

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 itself already gives solid descriptions for both parameters (question with 'natural language' and 'decomposition is the point'; depth with enum explanations). The description adds value by elaborating on the depth values' hop and contradiction behaviors, and by reinforcing that broad/multi-part questions are acceptable. However, because the schema already covers the basics, the description's incremental contribution is moderate, not full — hence a 4 rather than a 5.

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

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

The description states a specific verb ('research') and resource ('Pipeworx's 1500 STRUCTURED data sources') and clearly distinguishes it from open-web search and from sibling ask_pipeworx. It also names the key differentiator (parallel decomposition across 5,743 tools) and gives concrete example use cases, so an agent can disambiguate it without opening the schema.

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 and when-not-to-use guidance: it says to use ask_pipeworx for a single lookup and for breaking/current-news topics, and explains why (deep_research returns empty gaps). It also notes the account requirement and that thorough depth needs a paid plan, routing unauthenticated users to ask_pipeworx. This is actionable and leaves little to inference.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds meaningful context: it returns top-N tools with full input schemas and curated examples, and each result is ready to call directly without a second schema lookup. This goes beyond the annotations and informs the agent about the output format and efficiency.

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

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

The description is a single paragraph that is fairly concise and front-loaded with the core action. It efficiently conveys purpose, usage, and return value. However, it could be more structured (e.g., bullet points) for readability. No wasted sentences.

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

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

Given low complexity and good annotations, the description covers all necessary aspects: purpose, usage, return format, and readiness for direct invocation. No output schema is needed because the description explains what is returned. The tool is simple, and the description is complete for an agent to understand its role.

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 mentions that 'query' accepts natural language and gives examples (e.g., 'look up FDA drug approvals'), which adds some semantic value. However, the schema already includes descriptions like 'Natural language description of what you want to do'. The description does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool's purpose: to find tools by describing a data or task. It lists numerous specific domains (SEC filings, financials, etc.) and specifies that it returns top-N relevant tools with names, descriptions, and full input schemas. This distinguishes it from sibling tools like search_within or ask_pipeworx, which serve different functions.

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

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

The description explicitly advises to call this tool FIRST when you have many tools and want to see the option set, rather than just getting one answer. It also lists use cases (browse, search, look up, discover). However, it does not explicitly state when not to use it, e.g., if the agent already knows which tool to invoke.

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, and the description adds substantial behavioral context far beyond that: parallel fan-out across sources, soft-failure behavior for USPTO, FDA sections expected to be empty for some companies, source_used/source_failed semantics, and private-company fallback behavior. 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 and dense, but nearly every sentence carries necessary behavioral or usage information for a complex multi-source tool. It is front-loaded with example queries and the preferred-use directive. The main downside is that it is one sprawling paragraph without formatting that would aid scanning.

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

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

Despite having no output schema, the description thoroughly documents every major output field, edge cases, empty-result semantics, source failures, and acceptable input forms. An agent has enough context to invoke the tool correctly and interpret results across a wide range of user questions.

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 genuine value beyond the schema: type values are interchangeable, both parameter shapes accept all three input forms, and name resolution via SEC EDGAR is explained. This elevates it above baseline.

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

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

States a specific verb-resource pairing: producing a full cross-source profile of a US public company in one call. Example queries illustrate intent and make clear it is a holistic research tool, distinguishing it from single-pack lookups and sibling tools like compare_entities or resolve_entity.

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

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

Explicitly says ALWAYS PREFER this over chaining single-pack SEC/XBRL/news lookups when a holistic view is needed. It also clarifies what happens for private companies and name-based lookups, giving an agent clear decision rules for when this tool is appropriate.

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

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

Annotations provide destructiveHint=true; description adds context for why deletion is used (stale data, sensitive data), going beyond the annotation without contradicting it.

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

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

Two compact sentences with no wasted words; action and context are 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 simple one-parameter tool with strong annotations and schema, the description covers all necessary context: purpose, when to use, and relationship to siblings.

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

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

Schema coverage is 100% with clear description of 'key' parameter. Description does not add extra meaning beyond schema, so 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?

Description states 'Delete a previously stored memory by key' – a specific verb and resource. It distinguishes from sibling tools like 'remember' and 'recall' by naming them.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also directs to pair with 'remember' and 'recall', indicating 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 the tool as read-only and idempotent. Description adds value by outlining the process: fetches page, extracts title/description/key links, emits standard markdown. 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?

Three sentences: first states purpose and audience, second details method and output, third lists use cases. No unnecessary words, front-loaded with key information.

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

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

Given 2 simple parameters, no output schema, and comprehensive annotations, the description fully covers what the tool does, how it works, and what to expect. No gaps remain for an AI 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?

Schema coverage is 100% for both parameters. Description adds context: url can be full URL or landing page, max_links defaults to 25 max 50. This enriches what the schema provides without redundancy.

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

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

Description clearly states the tool generates an llms.txt file for any URL, with specific verb 'generate', resource 'llms.txt file', and scope 'for any URL'. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on producing the standard file format.

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 three explicit use cases: getting a client's site indexed, drafting for own project, auditing competitor visibility. While not specifying when to avoid, the examples give clear context for appropriate use.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds context about the actual data (countries/crises) and format, but no behavioral gaps or contradictions.

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

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

Two sentences, each serving a distinct purpose: definition and usage tip. No wasted words. Front-loaded with purpose.

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

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

Given the simplicity, good annotations, and no output schema, the description fully covers what an agent needs: what it returns (list of locations with ISO3 codes) and how to use it downstream.

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

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

Only one parameter 'limit' with 100% schema coverage. Description mentions default (300) and constraint (1-1000) but adds no new semantic meaning beyond the schema.

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

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

Clear verb 'List' and resource 'locations on HDX', with explanation of what locations are (countries and crises) and format (lowercase ISO3 key). Distinguishes from sibling tool 'list_organizations'.

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 how to use the output: 'Use a code as fq="groups:<name>" in search_datasets to scope results to a country/crisis.' Provides direct guidance to the agent.

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 annotations by specifying the tool returns UN agencies and NGOs and is CKAN's organization_list, which helps set expectations.

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

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

Two concise sentences with no unnecessary words. The first sentence sets the purpose, and the second adds a practical usage hint. Front-loaded and efficient.

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

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

For a simple tool with one parameter and no output schema, the description is complete. It explains what the tool does, provides examples, and ties to a sibling workflow. Annotations are rich, so no further context needed.

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

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

The schema description coverage is 100%, so the input schema fully describes the limit parameter. The description adds no additional parameter details, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists publishing organizations on HDX, specifying it's CKAN's organization_list and giving concrete examples of organizations. This distinguishes it from sibling tools like search_datasets.

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

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

The description provides guidance on using the output (org name) in search_datasets, hinting at a common workflow. However, it does not explicitly state when to use this tool versus alternatives or when not to use it.

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

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

Annotations already indicate read-only, non-destructive, idempotent behavior. Description adds that it returns specific fields and defaults to active subscriptions, with an option for inactive. No contradictions, but no mention of rate limits or other constraints beyond annotations.

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

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

Two sentences: first states action and return fields, second gives usage guidance. No wasted words, front-loaded with key information, highly efficient.

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

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

Given the simple tool (one optional param, no output schema, safe annotations), the description fully covers what it does, what it returns, and when to use it. Enumerated return fields compensate for lack of output schema.

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

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

Schema coverage is 100% with the single parameter include_inactive already described as 'Include cancelled subscriptions in the response (default false).' Description does not add further meaning to the parameter, so baseline 3 is appropriate.

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

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

Description clearly states the tool lists the caller's active subscriptions and enumerates return fields (id, type, params, created_at, last_fired_at, fire_count). It distinguishes itself from sibling tools subscribe and unsubscribe by focusing on listing and review.

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

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

Explicitly tells when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides clear context and alternative use cases, differentiating from other subscription management tools.

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

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

All annotations are false, so description carries full burden; it delivers: mentions the claim_token flow for unauthenticated filing, how to follow up, daily digest reads, rate limit (5/identifier/day), and that it's free/quota-exempt. These behaviors are not inferable from schema or 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 detailed yet each sentence adds unique value—purpose, use cases, exclusions, token lifecycle, and constraints. It is front-loaded with the core 'tell the team something is broken' purpose, then delivers operational details in a digestible sequence. Slightly long but 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?

No output schema exists, yet description covers what to expect (claim_token, later resolution read), and all four parameters are semantically clear from schema+description. It also handles edge cases like non-Pipeworx tools and rate limiting, making it self-sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100%, but description adds crucial semantic nuance: tells users to frame issues in terms of Pipeworx tools/packs rather than pasted prompts, and shows exact claim_token usage pattern. This goes beyond the raw enum/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?

Description opens with a concrete action ('Tell the Pipeworx team something is broken, missing, or needs to exist'), names the resource (Pipeworx team), and enumerates specific feedback types (bug, feature/data_gap, praise). This clearly distinguishes it from sibling research tools by specifying the feedback-only scope.

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

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

Explicit 'Use when' list covers bug, feature/data_gap, and praise scenarios. It also gives an explicit exclusion: only Pipeworx-served tools, not other MCP servers' tools, with an alternative ('file it with that server instead'). No further guidance needed.

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

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

The description adds significant context beyond annotations: it reveals the data source (CF analytics-engine), privacy guarantees (no PII), and caching behavior (5min-1h). This complements the readOnlyHint and idempotentHint already present.

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?

Every sentence adds value: it defines output, enumerates use cases, explains data source and caching. No filler, front-loaded with the key result. Ideal length for the complexity.

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

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

For a simple tool with one optional parameter and no output schema, the description covers what is returned (top tools, top packs, total call volume) and the time windows. It could specify the structure of the response (e.g., sorted lists with counts), but the information is sufficient for an agent's decision.

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 the parameter fully (enum values, default). The description adds usage guidance on window selection (short vs long windows) and reinforces the default, which goes beyond the schema.

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

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

The description clearly states what the tool returns (top tools, top packs, total call volume) with a specific verb and resource. It distinguishes itself from sibling tools by focusing on trending/aggregate data rather than direct answers 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, aligning needs) but does not explicitly state when not to use it or compare to alternatives. The context is clear enough for an agent to decide.

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

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

The description goes far beyond annotations, detailing internal checks (Jaccard similarity >0.30, placeholder filtering, partition_sum ≈1, fill check against live CLOB depth) and warning that realizable_edge_pp ≤ 0 means 'do not trade it.' No contradictions with readOnlyHint, openWorldHint, 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 purpose and structured by mode, but it is lengthy. Every sentence adds value, though some details (e.g., Jaccard threshold, placeholder filter) could be slightly condensed without losing clarity.

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

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

Given no output schema, the description thoroughly documents response fields (opportunities[], partition_check{}), fill check details, and edge cases (placeholder filters, low_similarity count). It is complete for guiding an AI agent's use and interpretation.

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

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

Schema coverage is 100%, and the description adds deep context: explains event slug vs URL acceptance, topic as a seed question, and the logic behind each mode (e.g., cross-event scanning catches date patterns single-event misses). This meaningfully extends the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between three modes (no args, event, topic) with specific resource targets, making it highly specific.

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

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

The description provides explicit guidance on when to use each mode: 'Call with NO args for a `trending_scan`... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' It also advises on when to avoid trades based on fill check, but does not directly contrast with sibling tools like polymarket_edges.

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

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

The description extensively discloses behavioral traits beyond annotations, including model methodologies, response segmentation, caching behavior, tradeable-edge knobs, and diagnostic outputs. This adds significant context 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 very long and detailed, containing technical formulas and verbose explanations. While information-rich, it lacks conciseness and could be better structured (e.g., bullet points) for agent efficiency.

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

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

Given the complexity (9 parameters, no output schema, multiple segments), the description is remarkably complete, covering response structure, diagnostics, and knob effects. Minor gap: output format of individual opportunities is implied but not fully described.

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

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

All 9 parameters are described in the schema (100% coverage), and the description adds extra meaning, e.g., explaining why min_kelly doesn't filter partition arbs and how slippage_pp interacts with Polymarket's zero fees.

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: scanning top Polymarket markets to return opportunities where Pipeworx data disagrees with market price. It specifies three model families, distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker by focusing on a broad discovery use case.

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

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

The description implies usage for 'what should I bet on today' and notes that it avoids paging hundreds of markets, providing clear context. However, it does not explicitly exclude alternatives or state when not to use it.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds extensive behavioral context: explains response structure (tracked[], expired[], snapshot_dates[]), data source limitations (snapshot TTL, cache-miss gaps), and computational details (decay from daily closes, not intraday). 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 front-loaded with the purpose and provides detailed response structure and limitations. It is informative but slightly verbose; every sentence adds value, though some details could be condensed without losing meaning.

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

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

With no output schema, the description fully explains the return values (tracked, expired, snapshot_dates arrays) and their semantics, including edge time-series, trend, decay, lifespan, and data gaps. It also covers limitations like the 60-day TTL and daily close granularity, providing complete guidance 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?

Both parameters are fully described in the input schema (100% coverage). The tool description repeats the schema's default values and constraints (e.g., 'default 14, max 30') without adding new semantic meaning beyond what is already in the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' and answers the specific question 'how long has this edge existed and is it shrinking?' It distinguishes from sibling tools like polymarket_edges by focusing on temporal analysis of edge persistence.

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 historical persistence analysis but does not explicitly state when to use this tool over alternatives. No direct comparisons or exclusions are provided, though the context of contrasting new vs old edges gives some guidance.

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

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

The description adds extensive behavioral context beyond the annotations: it explains ladder walking, return metrics (vwap_fill_price, slippage_pp, verdict), and critical warnings about thin legs and forced directional risk. Annotations indicate readOnly and idempotent, which the description confirms.

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

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

The description is lengthy but well-structured with sections for requirements, single-market, basket, and usage guidance. Every sentence adds value, though some pruning could improve conciseness. Given the complexity, it is appropriately detailed.

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

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

Despite no output schema, the description enumerates all return fields (top_of_book, vwap_fill_price, etc.) and explains verdicts, per-leg details, and risk indicators. It is complete enough for an agent to execute correctly in both modes.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains the 'market' vs 'event' requirement, default values, side auto-detection in basket mode, and the dual interpretation of size_usd. This greatly aids correct parameter usage.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It provides specific verbs and resources, 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?

The description explicitly tells when to use this tool: before acting on polymarket_arbitrage signals or trades above ~$500. It explains the risks of not using it (partial basket fills leading to unhedged positions), providing clear context and exclusions.

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

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

Beyond annotations, the description discloses extensive behavioral details: two modes run the same matcher, safety fields can be non-empty even when pairs are returned, compatibility codes are enumerated, flags per spread entry are listed, unknown metric_type/match_subtype legs are never paired, fees are gross not net, and temporal_alignment null semantics are explained. This far exceeds what annotations provide.

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

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

The description is well-structured with clear sections (modes, response, safety fields, fees, counters) and is front-loaded with the core purpose. However, it is quite long and contains some redundancy, such as temporal_alignment_unknown being explained twice and the 'pre-mapped ≠ tradeable' warning repeated. Still, the organization helps an agent parse the dense caveats.

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 and a complex response with many conditional safety fields, the description carries a heavy burden and meets it almost fully. It explains response structure, all compatibility codes, per-entry flags, skipped leg handling, temporal alignment semantics, fee disclosure, and the rarity of tradeable spreads. An agent has enough context to invoke the tool correctly 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 each parameter has a clear description. The tool description adds significant semantic value beyond the schema: it explains the mode selection between the three optional params, lists all valid topic values, describes how explicit ticker/slug override the topic-mapped side, and clarifies that both modes behave identically. This makes parameter intent fully clear.

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 resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes this tool from sibling polymarket tools by naming both venues and the spread concept, and further clarifies scope with mode details. The verb is implicit but the purpose is unmistakable.

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

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

The description clearly explains two usage modes (topic shortcuts vs explicit ticker/slug), when each is appropriate, and gives concrete examples for each. It also warns that pre-mapped topics often return compatibility_warning and that 'pre-mapped ≠ tradeable,' providing exclusion guidance. It does not explicitly name sibling alternatives, but the mode-selection guidance is strong.

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, destructiveHint. The description adds valuable context: scoping to user identifier and pairing with remember/forget, which goes beyond annotations.

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

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

Four sentences, each carrying essential information. No fluff. Front-loaded with the core action.

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?

Complete for a read-only lookup tool. Explains behavior with and without key, scoping, and relationship to sibling tools. No output schema needed as the return is obvious.

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

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

Schema coverage is 100% with a description for 'key'. The description adds clarity by explaining the effect of omitting the argument (list all keys) and provides real-world examples like 'user's target ticker'.

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

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

Clearly states the tool retrieves a previously saved value or lists all keys when omitted. The verb 'retrieve' and resource 'memory' are explicit, and it distinguishes from sibling tools 'remember' and 'forget'.

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

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

Provides explicit context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It implies when not to use (when you need new data), but does not explicitly state exclusions or list alternatives beyond mentioning pair tools.

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

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

Adds value beyond annotations by explaining mark_read semantics, poll-friendly nature, and alternative endpoint. No contradictions with 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?

Well-structured, front-loaded with purpose, then details. Every sentence adds value; no fluff. Appropriate length for a 5-parameter 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?

Covers key aspects: purpose, filtering, return fields, mark_read behavior, polling. Lacks explicit pagination details beyond limit, but limit parameter and 'most recent' wording suffice. No output schema but description hints at payload structure.

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 already covers all parameters with descriptions; description reiterates but adds minor context (e.g., 'sec_8k' type example, ISO timestamp format). No significant new information beyond schema.

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

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

Description clearly states it pulls fired events from subscription feed, specifies returned fields (source, citation_uri, raw payload), and distinguishes from sibling tools like list_subscriptions by focusing on event 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?

Provides clear usage patterns (filter by type/since, mark_read behavior) and mentions alternative access via GET endpoint. Lacks explicit when-not-to-use, but context is sufficient.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant context: parallel fan-out to multiple sources, fallback mechanism, soft-fail for USPTO, return structure (changes[] grouped by source, total_changes, citation URIs). No contradiction.

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

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

The description is a single well-structured paragraph, front-loaded with example queries. Every sentence adds necessary information: sources, fallback, parameter details, return format, and sibling differentiation. No fluff.

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

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

Given the complexity (multiple sources, fallbacks, edge cases) and lack of output schema, the description fully covers behavior, return structure, and error conditions (soft-fail, rate limiting). It is complete for an agent to invoke correctly.

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

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

Schema coverage is 100%. The description adds value by explaining each parameter: 'since' accepts ISO or relative shorthand with example, 'value' accepts ticker or CIK, 'type' has only 'company' supported. It also recommends typical window ('30d' or '1m').

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

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

The description explicitly states the tool provides a change feed for a company in a time window, lists the sources (SEC EDGAR, GDELT→GNews, USPTO), and distinguishes from sibling entity_profile which gives a static profile. The verb 'get' is implied, and the resource is clearly 'changes'.

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

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

The description provides example queries ('What's new with X', 'latest on Y'), explains when to use (monitoring changes over time), and explicitly says when not to use ('Use entity_profile instead when you want the static profile'). It also explains fallback behavior (GDELT→GNews) and date parsing.

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

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

Adds scoping and expiry details beyond annotations (idempotent, non-destructive). No contradictions.

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

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

Three concise sentences, no fluff, purpose 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?

Complete for a simple key-value tool: purpose, when to use, persistence behavior, and related tools.

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

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

Schema covers both parameters well; description adds context about key-value pairing but not substantial new info beyond schema.

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

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

Clearly states verb 'save' and resource 'data for later reuse', distinguishing it from siblings like recall and forget.

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

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

Explicitly says 'when you discover something worth carrying forward' and mentions pairing with recall and forget, providing clear usage context.

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

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

Annotations already indicate read-only, idempotent, open-world behavior, and the description adds substantial context: graceful degradation when GLEIF/OpenFIGI are unavailable, candidate-based ambiguity handling, explicit `unresolved` reporting, source labeling, and internal cascading through multiple lookup endpoints. No contradiction exists.

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 user-phrase examples and the core directive, and the dense supported-types section contains mostly essential operational details such as exact-name requirements and fallback behavior. It is slightly over-packed in the company section, preventing a perfect conciseness score.

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

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

Even without an output schema, the description explains input formats, expected returned identifiers (CIK, LEI, FIGI, RxCUI), ambiguous-match behavior via `figi_candidates`, explicit `unresolved` output, and enrichment fallback. An agent has sufficient information to call the tool correctly and interpret the response.

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 complete, and the description still adds critical semantics: `value` accepts ticker/CIK/name for companies and brand/generic for drugs, and it warns to pass only the entity name, not the full noun phrase (e.g., bond issue). This materially improves correct invocation.

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

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

The description states a specific verb and resource: resolving a user-spoken name to canonical/official identifiers other tools require as input, illustrated with concrete query examples. It is clearly distinguishable from siblings like entity_profile by emphasizing ID resolution and the directive 'Use FIRST whenever you have a name but need an ID.'

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

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

Explicit 'when to use' guidance is present ('Use FIRST whenever you have a name but need an ID') and the description lists trigger phrases and supported entity types. It does not name specific sibling tools or give when-not-to-use exclusions, but the intended context is clear.

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

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

Annotations declare the tool read-only, idempotent, and open-world. Description adds internal behavior ('probes each entity with ai_visibility_check') and output structure ('ranked list with score, confidence, signal density per entity'). No contradictions. Sufficiently discloses behavioral traits beyond annotations.

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

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

Two sentences: first states core action, second provides purpose and output. No wasted words, front-loaded, 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?

Given no output schema, description sufficiently explains return values (ranked list with score, confidence, signal density). All 4 parameters are implicitly covered. Complexities like optional _apiKey and context are addressed. No critical gaps.

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

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

Schema coverage is 100%, providing baseline 3. Description adds meaning: 'first entry treated as subject' for entities, 'omit for just workers-ai' clarifies default. This adds value beyond the schema alone.

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

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

Description clearly states the tool's purpose: comparing AI visibility across multiple entities, probing each with ai_visibility_check, ranking by score, and surfacing most/least recognized. The specific verb 'compare' and resource 'competitor AI presence' differentiate it from siblings like ai_visibility_check (single entity) and general 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?

Description provides a concrete use case ('competitive AI-marketing audits') and an example question. It does not explicitly state when not to use or contrast with sibling tools, but the context is clear enough for an agent to infer appropriate usage.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds valuable behavioral details: partial failures degrade gracefully, bundlephobia first measurement may take 5-30s, and sources_failed will list timed-out sources. No contradiction with annotations.

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

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

The description is well-structured: purpose first, then behavior details, then failure handling, then limitations. Every sentence adds value. Slightly long but justified by composite nature. Not maximally concise but no fluff.

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

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

The description fully explains what the tool returns (summary block with specific fields, advisory detail, links, alternative versions), handles partial failures, and notes ecosystem constraints. No output schema exists, so the description carries the full burden and succeeds.

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

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

Schema coverage is 100% with descriptions for both parameters. The description reinforces that scoped packages are accepted (already in schema) and version defaults to latest (already in schema). It does not add additional semantic meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description states a clear, specific verb-resource combination: 'Composite should I add this npm package to my project check in ONE call — fans out across deps.dev and bundlephobia'. It distinguishes from siblings by limiting scope to npm ecosystem and directing other ecosystems to deps.dev:version directly.

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

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

Explicitly tells when to use: 'Use whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. Also specifies when not to use: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds behavioral context: source (CKAN package_search), return fields (titles, descriptions, etc.), and filter capabilities, without contradicting annotations.

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

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

Two concise sentences front-loading purpose. Every sentence adds value; no 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?

Fairly complete for a search tool with 5 parameters and no output schema. Explains source, return fields, filtering, and references sibling. Could detail output format more, but adequate.

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

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

Schema coverage is 100%, baseline 3. Description adds significant meaning: explains fq usage with examples, suggests list_locations for codes, elaborates on query and sort. This goes well beyond the schema.

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

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

The description clearly states the tool searches the Humanitarian Data Exchange catalogue for specific topics like displacement, refugees, etc., and returns datasets with details. It distinguishes from siblings like list_locations by referencing them for codes.

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 (searching humanitarian datasets) and gives a concrete filter example with fq and reference to list_locations. It lacks explicit when-not-to-use statements but provides clear context.

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

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

Discloses technical details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. Annotations already mark as read-only/idempotent, but description adds implementation 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?

Every sentence contributes: purpose, use case, pairing advice, technical details, limits. Front-loaded with main action and use. No redundant or vague statements.

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

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

Despite no output schema, description fully explains return format (passages, offsets, similarity scores) and edge case (truncation). Covers input, output, usage pattern, and technical constraints completely.

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

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

Schema has 100% coverage with descriptions. Description adds value with examples for query field and clarifies limits in prose (1-20, default 5). This goes beyond schema but schema already good, so slight added value.

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

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

Clearly states the tool performs semantic search inside a fetched record, with specific examples (SEC 10-K, article) and output details (passages, offsets, scores). Differentiates from sibling tools by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly says to use when the record is too large for the prompt and suggests pairing with ask_pipeworx_grounded. Provides clear context for when it's beneficial, though no explicit when-not cases.

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

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

Annotations provide readOnlyHint=false (creates) and idempotentHint=true (safe to retry). Description adds key traits: requires OAuth, type-specific parameters, delivery constraints (SMS cap, webhook signing secret given once). No contradiction with annotations.

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

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

Description is front-loaded with purpose and prerequisite, then organized by type and delivery. It is relatively long but every sentence adds value. Minor redundancy in repeating delivery details could be trimmed.

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

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

Covers prerequisite, types with examples, delivery channels with constraints. Does not explain return value format beyond 'id', nor error cases like duplicate subscriptions. Adequate given no output schema and rich sibling set.

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. The description enriches parameters with examples (e.g., sec_8k items codes, polymarket_edge topic, delivery channel constraints) providing additional meaning beyond the schema.

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

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

The description clearly states the verb 'Create' and resource 'proactive monitoring subscription', and specifies it returns a subscription id. It is distinct from siblings like 'unsubscribe' (removal) and 'list_subscriptions' (listing).

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

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

Describes prerequisites (Pipeworx OAuth account) and supported types with examples. Hints at alternative delivery channels (feed, pull via recent_alerts) but does not explicitly contrast with other subscription tools like 'polymarket_edge_tracker' or when to use this vs. non-creating tools.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds details about return format (category-bucketed examples with exact tool+argument shape) and that it draws from live catalog. No contradictions.

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

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

Well-structured: starts with example questions, then describes return format and usage. Slightly long but each sentence adds value. Front-loaded with key phrases.

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, description explains return format (category-bucketed examples). Comprehensive for an onboarding tool with good annotations. Covers what, when, and how to call.

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 has 1 parameter (topic) with description. Description adds examples of focus areas and clarifies that omitting topic gives full spread. Schema coverage is 100%, so baseline is 3; description adds extra 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 clearly states the tool returns category-bucketed example questions and is the onboarding entry point. It uses specific verbs ('returns', 'draws from') and distinguishes from siblings by being the first tool to use when unfamiliar with Pipeworx.

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

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

Explicitly says to use this tool FIRST when you do not yet know what Pipeworx can do, and to learn how to call meta-tools. Provides guidance on optional topic parameter. Does not explicitly state when not to use, but context is clear.

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

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

Annotations already indicate non-readOnly, idempotent, non-destructive. The description adds critical behavioral context: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts' and ownership enforcement. No contradictions.

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

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

Two concise sentences: first states the action, second adds behavioral details. Every sentence is necessary and front-loaded. No fluff.

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

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

For a simple tool with one required parameter, no output schema, and rich annotations, the description covers purpose, ownership, effect, and connection to related tools (recent_alerts). Complete enough for correct usage.

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

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

Schema coverage is 100%, and the schema already describes the id parameter as 'Subscription id (uuid) returned by subscribe.' The description only says 'by id,' adding no new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id,' specifying the verb (cancel), resource (subscription), and parameter (id). It differentiates from sibling tools like 'subscribe' and 'list_subscriptions' by its cancellation purpose and ownership enforcement.

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 implicitly indicates when to use: to cancel a subscription you own. It mentions ownership enforcement ('you can only cancel your own subscriptions') and the effect (deactivation, not deletion), but does not explicitly compare to alternatives or state when not to use.

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

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

The description significantly expands beyond annotations by explaining the dual-pipeline behavior, the return verdict list, and crucially the semantics of 'could_not_verify' (check did not happen, not evidence) and 'unsupported' (no source covers it). This is high-value context that annotations alone (readOnly, idempotent, openWorld) do not convey.

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

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

The description is long but appropriately front-loaded with trigger phrases and core purpose. Every section add necessary context: trigger phrases, pipeline routing, return verdicts, and caller warnings. The 'Replaces 4–6 sequential calls' line is somewhat promotional but informative about efficiency. Slightly verbose, but no 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?

Given the tool's complexity (two processing paths, multiple verdict types, special error semantics) and no output schema, the description does an excellent job covering return values and their meanings. It also explains the fallback behavior for any non-financial claim. An agent has enough information to use this tool correctly 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%, so the baseline is 3. The description adds value for tolerance_pct by explaining it overrides the claim's implied tolerance and recommending 1-2 for hallucination detection. It also provides realistic examples for the claim parameter, going beyond the schema's generic examples.

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

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

The description specifies a clear verb+resource: 'natural-language claim verification against authoritative sources.' It includes concrete trigger phrases and distinguishes from sibling tools by focusing on fact-checking user claims, with two clearly delineated paths (structured SEC/XBRL vs grounded pipeline).

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies when to use the structured financial path vs the generic grounded path. However, it does not explicitly name alternative sibling tools or state when not to use it, 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.