Avoindata Fi

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations, such as the free default model versus the 'BYO key' cost implication for Anthropic calls, and the return structure per model. This is useful for understanding side effects (none) and cost behavior.

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

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

The description is three sentences long, front-loaded with the core purpose, followed by cost/configuration details and use cases. Every sentence adds meaningful information with no filler or repetition. It is efficiently structured and easy to scan.

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

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

The tool has no output schema, so the description responsibly includes a return-shape summary: per-model score, confidence, signals, raw_response, plus a combined view. It also clarifies default behavior and optional parameters. Minor vagueness around 'signals' and 'combined view' prevents a higher score, but overall it is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with each parameter described. The description adds extra context beyond the schema: the default model, the fact that _apiKey is passed straight through to Anthropic, and the optional nature of models. This supplements the schema without redundancy, justifying a score above the baseline.

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

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

The description clearly states the tool's function: probing one or more LLMs for knowledge about a business/brand/product/topic and scoring visibility from 0-100 per model. It also mentions the default model and optional Anthropic probe, distinguishing it from other AI research tools in the sibling list such as deep_research or ask_pipeworx.

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

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

The description provides clear context on when to use the tool: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains the default model and when to pass _apiKey, but it does not explicitly name alternative tools or exclusion criteria, so it stops short of full when/when-not guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds that it is the default entry point, works on every tier, one fast call, fills arguments, returns stable citation URIs, and implies a limitation by recommending ask_pipeworx_grounded for hallucination-resistant answers. 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?

While long (~170 words), the description is front-loaded with a strong usage directive and structured in sections: usage scope, mechanics, examples, default entry point, and alternatives. Every sentence adds relevant guidance, making the length justified.

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

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

Given no output schema, the description adequately explains what the tool returns (structured answer with pipeworx:// citation URIs) and covers prerequisites (works on every tier), performance (one fast call), and alternatives. It is complete for a broad question-answering tool.

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

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

Schema covers all 6 parameters with 100% coverage, mostly aliases. The description goes beyond the schema by specifying the type of questions to ask ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') and providing six concrete examples, giving the agent practical guidance for formulating the input.

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

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

The description clearly states a specific verb-resource combination: routes questions to 5,462 tools across 1419 verified sources and returns structured answers with citation URIs. It distinguishes from siblings by naming ask_pipeworx_grounded and deep_research, and by positioning itself as the default entry point.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and 'Use whenever the user asks...', gives concrete examples, and provides explicit alternatives for when to step up: ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad multi-part questions. It also clarifies handling of breaking news.

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

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

The description goes beyond annotations by disclosing its beta status, the live testing of candidate routing improvements, and the lack of fallback (it is a full working router). This adds valuable context about experimental behavior and comparisons without contradicting the readOnlyHint or idempotentHint 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 moderately detailed but each sentence contributes meaningful information: beta status, current state, usage instruction, and clarification of functionality. It is not overly verbose, though some redundancy exists (e.g., 'identical' and 'matches exactly').

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 covers what an agent needs: what it does, how it differs from the stable version, how to use it, and what to expect (same response shape). It is complete given the rich annotations and the tool's complexity.

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

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

Schema coverage is 100%, with the 'question' parameter and aliases clearly documented. The description adds marginal value by stating 'same arguments' as ask_pipeworx, but does not enrich parameter semantics beyond what the schema already provides, 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 this is a beta version of ask_pipeworx, a universal router that accepts questions and routes to over 5,000 tools. It distinguishes itself from the sibling ask_pipeworx by emphasizing its experimental routing improvements and current alignment with the stable router.

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

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

Explicit guidance is provided: 'Use it exactly like ask_pipeworx when you want the newest routing,' and it clarifies that results are compared against the stable router. It also mentions that no candidate is currently active, so behavior matches ask_pipeworx exactly, giving clear when-to-use 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?

Beyond annotations, the description discloses that the answer is extracted ONLY from tool results, lists explicit refusal reasons, and mentions the additional LLM call. These are valuable behavioral insights not present in the readOnly/idempotent hints, with no contradiction observed.

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 serves a purpose: mode definition, routing comparison, return format, refusal reasons, usage guidance, and cost tradeoff. The JSON return shape is justified because there is no output schema. It is appropriately sized for a complex tool.

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

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

Given no output schema, the description thoroughly covers return values, failure modes, usage conditions, and cost. Combined with the schema's alias documentation and annotations (readOnly, idempotent, open world), the agent has enough to invoke it correctly in high-stakes scenarios.

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 all parameters are aliases for 'question' with clear descriptions. The tool description adds context about routing/fetching but no parameter-specific details beyond what the schema already provides, so it stays at the baseline for fully documented parameters.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads' and clearly distinguishes itself from ask_pipeworx by explaining the same routing but with extraction limited to tool results. This specific verb+resource+scope makes the purpose unmistakable and differentiates it from siblings.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on' and gives a direct alternative: 'prefer ask_pipeworx for casual lookups.' It also notes the extra LLM call cost, providing a clear tradeoff-based usage rule.

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, but the description goes far beyond: it discloses that low-confidence matches short-circuit and suppress analysis fields, closed markets return status:market_closed_or_inactive, wide-spread markets carry tradeability:illiquid_wide_spread, and cancellation rules are parsed to quantify EV impact. It even reveals fallback behavior for GDELT 429s. This is exemplary behavioral disclosure.

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

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

The description is long but every sentence earns its place for a tool of this complexity. It is front-loaded with the core purpose and then organized into labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY, etc.). There is no fluff or repetition; the density is justified given the many edge cases.

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

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

Despite no output schema, the description thoroughly documents the response structure: result.market, result.analysis, result.evidence, result.market_match fields, parent_event, news fields with fallback flags, and status values. It even warns about resolution-rule risk (flat-50¢ void settlements) with a concrete example. This is exceptionally complete for a high-complexity research tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value beyond schema: it explains the market param accepts slug/URL/text, depth quick vs thorough maps to 2-3 sources vs full fan-out, and include_raw controls response size (~20KB vs 50-500KB). It also ties fan-out behavior to classifier examples, giving agents deeper understanding of how parameters affect execution.

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

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

The description opens with a specific verb+resource+scope: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It then describes the full pipeline (resolve, classify, fan out, compare) and gives usage phrases ('should I bet on X', 'is there edge in Z'). This clearly distinguishes it from siblings like polymarket_edges or polymarket_arbitrage.

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

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

The description explicitly states when to use the tool ('Use for should I bet on X...') and provides rich context like classifier examples and fan-out patterns. It also explains blocking conditions (low-confidence, closed markets) that prevent misuse. However, it does not explicitly name alternative tools or say when not to use it, so it stops short of a 5.

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

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

Annotations already mark it as read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), correct handling of off-calendar fiscal years, sorting by primary metric, and citation URI returns. 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 compact but information-dense, front-loading user intent phrasings and ending with an efficiency claim. Every sentence serves a purpose with no fluff or repetition.

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

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

For a tool with two entity types, varying data sources, and sorting behavior, the description covers all essential aspects: input specifics, output awareness (paired data, citation URIs), and efficiency rationale. No output schema exists, but the description fills the gap.

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

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

Schema has 100% parameter coverage with descriptions for each param, but the description goes further by explaining what each enum value does ('type=company' pulls latest 10-K metrics, 'type=drug' pulls adverse-event counts) and provides examples for the values array. This adds 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 explicitly states it performs side-by-side comparison of 2–5 companies or drugs in ONE parallel call, with specific verbs like 'compare', 'rank', and 'head to head'. It distinguishes from sequential single-entity lookups, clearly differentiating it from entity_profile and other sibling tools.

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

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

Provides explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and lists example query phrasings. It also notes that it replaces 8–15 sequential lookups, giving clear direction on when to invoke this tool over alternatives.

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

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

Annotations already cover read-only and non-destructive behavior, so the added value comes from clarifying the output scope: 'including all resources and their resource_ids'. This gives the agent an expectation of what the response will contain, which is useful beyond the annotation hints. No contradictions with annotations are 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?

The description is a single, compact sentence that starts with the verb 'Show'. Every phrase adds value: what, for which resource, how to identify it, and what's included. No filler or redundant information is present.

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 only one parameter and no output schema, the description is quite complete. It specifies the input (id or name from search_datasets) and the expected output (full metadata, resources, and resource_ids). The annotations provide safety context, and the description fills in the behavioral detail needed for an agent to invoke it correctly.

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

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

The input schema already provides a full description for the 'id' parameter ('Dataset id or name (from search_datasets).'), and the tool description essentially repeats this information. With 100% schema coverage, the description adds no new semantic meaning to the parameter, hence the baseline score of 3.

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

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

The description clearly states the action ('Show full metadata'), the target resource ('one Finland Open Data dataset'), and the method of identification ('by id or name'). It distinguishes from sibling tools like search_datasets by specifically focusing on a single dataset's full details, including resources and their resource_ids.

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

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

The description implies usage after search_datasets by specifying 'from search_datasets', indicating the expected workflow. It provides clear context for when to use this tool (to get detailed metadata for a specific dataset), but it does not explicitly name alternatives or exclusions, such as when to use query_resource instead.

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

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

Even with annotations declaring readOnlyHint/openWorldHint/idempotentHint, the description adds substantial behavioral context: expected latency (15-60s, thorough ~90s), account/paywall requirement, output structure (findings packet with evidence, confidence, source, fetched_at, citations, gaps[], contradictions[]), and semantic excerpting behavior. No contradiction with annotations.

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

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

The description is long but dense, with every sentence contributing operational value (auth, latency, limitations, citation behavior). There is no filler, though it could be better structured with bullets or sections for scannability. Slight deduction for readability.

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

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

Despite no output schema, the description fully covers return value semantics (findings packet, gaps[], contradictions[], citation_uri resolvability), performance expectations, auth prerequisites, and exclusions. It anticipates the agent's need to decide when to invoke this complex tool and what to expect afterwards.

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

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

Schema coverage is 100% and both parameters are thoroughly described: question is free-form, depth enum explains each value with facet counts and hop behavior. The description adds usage context but no new parameter syntax or constraints. Per rubric, baseline 3 applies when schema does the heavy lifting.

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

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

The description states a specific verb+resource: "Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources" and explicitly contrasts with ask_pipeworx to distinguish itself. It also clarifies what it is NOT (not open-web search). This unambiguously defines the tool's purpose.

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

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

Provides explicit use cases: "Best for broad/multi-part questions over structured data" and explicitly says when to use alternatives: "For a single lookup use ask_pipeworx" and "For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx". Also gives auth guidance (if not signed in, use ask_pipeworx). This is textbook 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?

The description adds behavioral context beyond the read-only annotation: it discloses that results are ready-to-call with full schemas, no second lookup needed, and that it returns top-N. This complements the idempotentHint and readOnlyHint without contradiction.

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

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

The description is a single paragraph but well-structured: purpose, domains, output, strategic advice. While the domain list is long, it's useful for an agent to know the coverage, and each 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?

The tool is a discovery meta-tool; the description covers what it does, when to use, what it returns, and how to use it. No output schema is present, but the return values are explicitly described, making it complete 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%, and the description references the 'query' parameter's natural language format and the 'limit' as top-N. However, the description doesn't add substantial syntax or semantics beyond the schema's detailed field descriptions, 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's function: finding tools by describing data or task. It distinguishes itself from sibling tools by emphasizing it returns a ranked list of tools with schemas, and explicitly says to call it first for option discovery.

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

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

Explicitly states when to use: 'when you need to browse, search, look up, or discover what tools exist' and lists specific data domains. It also tells the agent to call this FIRST when many tools are available, contrasting it with getting 'just one answer.'

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

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

The description adds substantial behavioral context beyond the annotations: it reveals the tool fans out across SEC EDGAR, XBRL, USPTO, news, and GLEIF, returns specific fields, and mentions soft-fail behavior for the USPTO API sunset and a GDELT→GNews fallback. This is consistent with the readOnly, openWorld, and idempotent hints.

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

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

The description is well-structured and front-loaded with example user queries, then explains the parallel call nature, then lists return fields, and ends with input instructions. Every sentence provides useful information for a complex tool, with no redundant 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 there is no output schema, the description carefully enumerates all returned fields (CIK, company name, filings, fundamentals, patents, news, LEI) and important caveats (USPTO sunset, soft-fail, fallback). This fully equips an agent to understand what the tool does and what to expect, especially for a read-only, open-world operation.

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

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

The schema already documents both parameters (type and value) with detailed descriptions, including examples and the 'names not supported' caveat. The description essentially repeats this information without adding new parameter semantics, so it meets the baseline for high schema coverage.

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

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

The description clearly states the tool creates a full cross-source profile of a US public company, with specific query examples ('Tell me about X', 'company profile for Microsoft'). It distinguishes itself from sibling tools by mentioning it should be preferred over chaining single-pack SEC/XBRL/news lookups and noting that resolve_entity should be used for name-based lookups.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and directs users to resolve_entity if only a company name is available. This provides clear when-to-use and alternative guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, covering the safety profile. The description adds the 'clear sensitive data' context and 'previously stored' qualifier, but does not disclose additional behaviors like whether deletion is permanent or what happens if the key does not exist. This is acceptable given annotation coverage, but the description could offer slightly more behavioral detail.

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

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

Two sentences, front-loaded with the core action, then usage guidance, then relationship to siblings. Every sentence earns its place; no filler or redundancy.

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

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

For a simple one-parameter tool with strong annotations, rich schema (100% coverage), and no output schema, the description fully covers purpose, when-to-use, and relationship to siblings. No gaps that would prevent correct tool selection or invocation.

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

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

The input schema has 100% coverage with parameter 'key' described as 'Memory key to delete'. The description says 'by key', reinforcing the parameter but adding no new meaning. The schema also provides an example ('user_research_topic'), so the description does not need to compensate. 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 'Delete a previously stored memory by key' with a specific verb (delete) and resource (memory), immediately distinguishing it from sibling tools remember and recall. It also clarifies that it works on previously stored items, reinforcing its complementary role.

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 defines when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' This provides clear situational guidance and implicitly contrasts with remember and recall by context. The pairing note 'Pair with remember and recall' further orients the agent toward appropriate selection.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds behavioral details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This provides useful context about the tool's network access and output behavior beyond the annotations.

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

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

The description is efficiently structured: first sentence states the core function, second explains the process, third describes the output, and a final sentence lists use cases. Every sentence contributes value without redundancy.

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

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

The description covers what the tool does, how it works, the output format, and common use cases. It doesn't mention edge cases like unreachable URLs, but for this simple two-parameter tool with strong annotations, it is sufficiently complete.

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

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

Schema coverage is 100%, with both 'url' and 'max_links' described in the schema. The description adds minor context by mentioning 'key links' and 'any URL', but it doesn't add significant meaning beyond the schema, so the baseline score of 3 applies.

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

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

The description explicitly states the tool's function: 'Generate a production-ready llms.txt file for any URL' with a clear output format. It also differentiates from sibling tools by focusing on generating the file, rather than scanning or auditing AI presence.

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 concrete use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives clear context for when to use the tool, though it doesn't explicitly mention 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds return field specifics, but no additional behavioral traits like pagination or limits. This is adequate but not rich.

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

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

Two sentences, front-loaded with the action and return fields, no fluff. Each sentence earns its place.

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

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

For a simple list tool with strong annotations and schema, the description covers purpose, return format, and usage context. It does not mention include_inactive or pagination, but these are covered by the schema and the low complexity makes this sufficient.

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

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

Schema coverage is 100% for the single parameter (include_inactive) with a clear description. The tool description does not add parameter details beyond the schema, which is acceptable given the baseline.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields (id, type, params, etc.). This directly differentiates it from sibling tools like subscribe and unsubscribe.

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

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

Provides explicit usage context: review what you're monitoring before adding more subscriptions, or find an id to cancel. This is clear guidance, though it does not explicitly name alternatives or exclusions.

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

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

Annotations are all false and provide no safety clues, so the description carries the full burden. It discloses rate-limiting (5 per identifier per day), zero cost ('doesn't count against your tool-call quota'), daily team review, and advises against pasting user prompts. This goes well beyond the annotations.

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

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

The description is front-loaded with the core purpose and uses multiple sentences to convey necessary constraints. While somewhat verbose, each sentence addresses a distinct aspect (use cases, exclusions, content style, rate limit), making it well-structured 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 feedback tool with no output schema and minimal annotations, the description covers purpose, when to use, exclusions, message formatting, rate limits, and cost. This is complete enough for an agent to decide when and how to invoke it without ambiguity.

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

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

Schema coverage is 100% with detailed descriptions for all parameters including enum values and field explanations. The tool description adds minor guidance about framing feedback in terms of Pipeworx tools/packs, but this is more usage advice than parameter semantics. 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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific use cases (bug, feature/data_gap, praise) and distinguishes itself from sibling tools like ask_pipeworx by focusing on feedback rather than questions.

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

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

Provides explicit when-to-use guidance (bug, feature, data_gap, praise) and when-not-to-use (tools from other MCP servers). Includes a clear heuristic: 'Pipeworx tool names are the ones this connection lists.' This gives the agent strong contextual signals for choosing this tool.

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

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

Annotations already mark it readOnly, idempotent, and non-destructive. The description adds valuable context: derived from CF analytics-engine, no PII, output structure (pack, tool, count), and cache freshness (5min-1h). This goes well beyond what structured annotations 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?

Four sentences plus a compact list, front-loaded with the core purpose. Each sentence adds relevant detail (returns, use cases, aggregation privacy, caching) with no filler or redundancy.

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

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

With one parameter, no output schema, and robust safety annotations, the description still covers output structure, use cases, data provenance, PII, and caching. This is sufficient for an agent to decide when to call it 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?

The input schema has 100% description coverage for the single `window` parameter, including semantics for short vs long windows. The main description only repeats the values without adding new meaning, so a baseline score of 3 is appropriate.

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

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

The description opens with 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d)', providing a specific verb and resource. It clearly distinguishes this trending tool from siblings like discover_tools by focusing on aggregate call volume.

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 use cases: discovering hot data sources, confirming canonical tools, and aligning use case with agent demand. However, it doesn't name alternatives or provide exclusion criteria, so it stops short of a full 5.

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

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

Annotations already declare safe read-only behavior; description adds real behavioral constraints: >3pp deviations trigger every-leg signals, Jaccard ≥0.30 similarity filter, placeholder fraction cap, and the critical fill-check limitation (do not trade if realizable ≤0). No contradiction with annotations; the extra context materially changes how an agent should act.

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

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

Long but densely informative; labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) make it scannable. Every segment contributes operational knowledge, though it could be trimmed slightly without losing essential context.

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

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

Despite no output schema, it enumerates the response shape (opportunities[], partition_check, fill data) and handles error/limitation conditions. Combined with annotations, it leaves little ambiguity for an agent, covering modes, thresholds, filters, and real-world edge-case behavior.

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 params fully; description enhances them with concrete examples (fed-decision-may-2026, Strait of Hormuz) and differentiates event vs topic modes, including the cross-event flattening behavior. The examples and mode distinctions add substantial meaning beyond the schema's basic string descriptions.

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

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

The description opens with a specific verb-resource pairing ('Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks') and clearly distinguishes from sibling tools by naming arbitrage detection, not just edge listing or fill risk. This is a clear, differentiated purpose statement.

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 maps invocation patterns: no args → trending_scan, `event` → single-event, `topic` → cross-event, and gives situational recommendation ('recommended for a specific market'). It also names the alternative `polymarket_fill_risk` for custom sizing, creating clear when-to-use vs when-not-to-use 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/idempotent, but the description adds substantial behavioral detail: cache behavior ('Cached 1h at the KV level keyed on all knobs'), response structure, edge metrics, 24h-move warnings, diagnostics, and exclusions (Fed bets). 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?

Although long, it is tightly structured with uppercase section headers and every sentence carries purpose (e.g., specific alpha values, gate thresholds). The main purpose is front-loaded, and the density is justified by the tool's complexity.

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

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

With no output schema, the description fills the gap by detailing top-level response sections (by_segment, fed_candidates, _diagnostics), what each opportunity contains, and why segments might be empty. It also discloses caching and Fed signal limitations, making it highly complete.

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

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

Schema coverage is 100%, but the description adds meaning beyond schema: it groups parameters as 'TRADEABLE-EDGE KNOBS' and explains why min_partition_leg_kelly exists (parent kelly is 0 for partitions). This depth goes well beyond the schema's individual descriptions.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further distinguishes itself by naming three response segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), setting it apart from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 clearly frames when to use the tool: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It gives context but does not explicitly name alternatives or exclusions, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds valuable behavioral detail: snapshots are written on cache-miss so gaps are meaningful, decay is computed from daily closes of edge_pp_net (net of default slippage) not intraday, and history depth is bounded by TTL. These details go beyond the annotations and are critical for interpreting results.

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

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

The description is long but well-structured: purpose, argument summary, RESPONSE section with field semantics, and LIMITS. Every sentence adds value—the response section is essential since there is no output schema, and the LIMITS section prevents misinterpretation of gaps and decay precision. No fluff.

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

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

Despite no output schema, the description fully explains the response structure (tracked[], expired[], snapshot_dates[]) and their semantic meaning. It also covers edge cases (snapshot gaps, TTL, intraday vs. daily) and parameter clamping. The tool is well-contextualized for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100%: both parameters have descriptions including defaults (days default 14, window default '1wk'). The description adds minimal extra meaning—'window (snapshot family)' and mentions max 30 for days, which the schema already covers with 'clamp 2-30.' The baseline of 3 is appropriate for high schema coverage.

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

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

The description opens with a specific verb phrase 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and clearly states what the tool answers: 'how long has this edge existed and is it shrinking?' It explicitly contrasts fresh vs. old wide edges, which distinguishes it from sibling tools like polymarket_edges that report current 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 defines the exact use case (tracking edge persistence/decay) and provides important context like history depth being limited by the 60-day TTL and snapshot gaps meaning 'nobody scanned that day.' It does not explicitly name sibling alternatives or say 'use polymarket_edges for current edge values,' but the context is strong enough to guide 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?

While annotations declare read-only, the description discloses substantial behavioral detail: it 'walks the ladder', returns specific fields like slippage_pp and shares_filled, and warns that 'partial basket fills convert an arb into an unhedged directional position (the dominant loss mode).' This goes well beyond annotations.

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

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

The description is long and dense, but it is structured into clear single-market and basket sections with a final usage note. Every sentence conveys meaningful detail for a complex tool with two modes. It could be tightened, but the structure helps navigate the length.

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

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

Given the tool's complexity, the description covers modes, parameter semantics, return fields, and risk warnings. It even identifies failure modes (thin books, partial fills) and names outputs. No output schema exists, but the description enumerates all key return values, making it complete.

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

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

The schema has descriptive text for each parameter, and the description adds critical context: it mandates 'one of `market` (single-market mode) or `event` (basket/partition mode)', explains how size_usd is interpreted differently in each mode, and clarifies defaults. This adds 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 opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from siblings by naming polymarket_arbitrage and polymarket_edges and positioning this tool as the pre-trade risk check.

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

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

Explicit guidance is given: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when to use single-market vs basket mode, providing clear context and alternative-specific instructions.

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

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

Beyond the read-only and idempotent annotations, the description discloses critical behavioral traits: compatibility_warning fires under two distinct conditions, temporal_alignment indicates whether spreads are meaningful across calendar gaps, and skipped_cross_type/subtype counters expose dropped leg comparisons. This is far more than annotations provide and fully informs the agent of limitations.

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

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

The description is long but every sentence carries essential information, using capitalized labels (TWO MODES, RESPONSE, SAFETY FIELDS) to structure content. It is front-loaded with the core purpose and each additional detail earns its place, though a more formatted layout could improve scannability.

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

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

Given the tool's complexity (3 optional params, no output schema, nuanced compatibility logic), the description is remarkably complete. It covers input modes, response composition including leg-by-leg probabilities and top spreads, all safety field condition cases, and a practical warning about pre-mapped topics. There is no significant missing context for correct selection and invocation.

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

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

The input schema already covers each parameter individually (100% coverage), but the description adds conceptual structure by presenting 'topic' and explicit overrides as two modes, and explains how kalshi_event_ticker and polymarket_event_slug auto-fetch matching events. This extra context helps the agent understand the interplay between parameters beyond simple descriptions.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, with a specific scope that differentiates it from other Polymarket tools. It uses a specific resource (Kalshi vs Polymarket) and details two modes, making the purpose explicit.

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

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

The description provides clear context on when the spread is meaningful (equivalent bet shapes) and when it is not, and explicitly warns that most pre-mapped topics return compatibility_warning today, implying they are not tradeable. While it does not name alternative sibling tools, it gives enough guidance for an agent to decide whether this tool's output is reliable.

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

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

Annotations already declare this is a safe read operation (readOnlyHint, destructiveHint false). The description adds a valuable behavioral constraint: only resources with DataStore enabled are queryable, which is not apparent from annotations or schema. This adds context beyond structured fields, warranting a score above baseline.

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, front-loaded sentence followed by a brief note. Every word earns its place: the action, the resource type, the key parameters, and the critical caveat. No redundancy or fluff.

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

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

For a simple query tool with strong annotations and full schema coverage, the description covers the essential context: what it does, how to invoke it, and a non-obvious prerequisite. It does not detail the return format, but the phrase 'Pull rows' plus the overall simplicity make it sufficiently complete for an agent to use correctly.

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

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

Schema coverage is 100%, with each parameter described in the schema. The description only repeats the optional params (q, limit, offset) and mentions resource_id's origin, but adds little beyond the schema. Baseline 3 is appropriate since the schema carries the parameter documentation burden.

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

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

The description clearly states the tool's function: pulling rows from a tabular Finland Open Data resource via resource_id. It uses a specific verb ('Pull rows') and identifies the resource type (CKAN DataStore), distinguishing it from sibling tools like search_datasets that search datasets rather than querying specific resource data.

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

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

The description implies usage context: it's for querying a specific resource after identifying it from a dataset's resources. It also includes a useful caveat (only DataStore-enabled resources are queryable). However, it does not explicitly name alternative tools or provide exclusionary guidance, though the context is clear.

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

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

Annotations already state readOnlyHint=true and destructiveHint=false, so the description adds value by disclosing scoping to the agent's identifier and the dual behavior of retrieving a single key vs listing all keys. This goes beyond the schema and annotations.

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

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

Three sentences, front-loaded with the core action. Each sentence provides distinct value: action, use cases, then scoping and relationships with remember/forget. No redundant or irrelevant text.

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 read tool with strong annotations and a clear schema, the description covers purpose, usage, scoping, and related tools. It does not describe return behavior for a missing key, but given the idempotent, read-only nature, this is a minor gap.

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

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

The schema already covers the key parameter with 'Memory key to retrieve (omit to list all keys)' and examples. The description reiterates this but adds no new parameter-level semantics beyond the schema, meeting the baseline for 100% schema coverage.

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

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

The description opens with 'Retrieve a value previously saved via remember, or list all saved keys', which clearly states the verb and resource. It distinguishes recall from the sibling tools remember and forget, making its purpose unambiguous.

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

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

The description provides clear when-to-use guidance: 'Use to look up context the agent stored earlier' with concrete examples (target ticker, address, research notes). It pairs with remember and forget but does not explicitly name alternative tools to avoid for external data retrieval, so it lacks a full exclusion list.

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

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

The description discloses a mutating side effect (mark_read flag changes read state) and non-idempotent behavior, which directly contradicts the annotations readOnlyHint: true and idempotentHint: true. Despite being transparent, the mismatch warrants a score of 1 per the rubric.

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

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

Five sentences, entirely informative, front-loaded with the purpose, no fluff, and includes a helpful external reference.

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

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

The description covers the return payload, filtering, mark_read side effect, polling suitability, and an alternative HTTP endpoint. With the schema covering parameter details, this is complete for a read-style tool.

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

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

Schema covers all parameters with descriptions, and the description adds a concrete example for type ('sec_8k'), and explains the effect of mark_read beyond the schema's simple 'Flag the returned events read'.

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

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

The description opens with a specific verb ('Pull') and resource ('fired events from your subscription feed'), and distinctively describes the returned payload and filtering options, clearly distinguishing it from sibling tools like list_subscriptions or recent_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?

It explains suitable use cases (polling) and offers an external alternative for scripts/dashboards, but doesn't explicitly compare to sibling tools 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 declare readOnly=true, openWorld=true, idempotent=true, and destructive=false. The description adds significant context: it fans out to multiple external sources, explains fallback logic (GDELT→GNews), notes the USPTO soft-fail due to PatentsView sunset, and describes the return structure (changes[], total_changes, citation URIs). No contradiction with annotations.

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

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

The description is dense with useful information but still reasonably sized given the tool's complexity. It leads with the core purpose and then covers details. A few introductory example phrases could be trimmed without loss, but they help with discoverability.

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 multi-source behavior (SEC, GDELT/GNews, USPTO), the description thoroughly covers inputs, outputs, and limitations. Despite no output schema, it describes the return structure clearly. No important gaps exist for an agent to invoke it correctly.

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

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

Schema coverage is 100% and the schema already describes each parameter. The description adds extra guidance, such as accepting ISO dates or relative shorthand and recommending '30d' or '1m' for typical monitoring, which goes beyond the schema's basic descriptions.

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

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

The description explicitly states the tool's purpose: 'change feed for a company in the last N days/weeks/months' and provides natural-language example queries. It also distinguishes itself from the sibling tool entity_profile, making its scope clear.

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

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

The description gives concrete guidance on when to use this tool (for recent changes/news/filings/patents) and explicitly says 'Use entity_profile instead when you want the static profile...'. It also explains fallback behavior (GDELT to GNews) and the `since` parameter's recommended values.

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 non-read-only, idempotent, and non-destructive. The description adds valuable context beyond annotations by explaining persistence behavior (24 hours for anonymous sessions, persistent for authenticated users) and scoping by identifier, which is critical for agent decision-making.

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

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

The description is efficiently structured in five short sentences, each serving a distinct purpose: defining the action, specifying when to use it, explaining the storage model, noting persistence nuances, and identifying related tools. No fluff or redundant content.

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

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

For a simple two-parameter write operation with no output schema, the description fully covers the tool's role, usage triggers, storage behavior, and complementary actions. It leaves no critical gaps for an agent deciding whether and how to invoke the tool.

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

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

The input schema provides full descriptions and examples for both parameters, covering 100% of the semantics. The description reinforces the key-value model but does not add new parameter-specific details, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific, action-oriented phrase ('Save data the agent will need to reuse later') that clearly defines the tool's purpose. It distinguishes itself from siblings by explicitly naming complementary tools (recall, forget) and clarifying the memory storage use case, making it unmistakable when this tool is appropriate.

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 direct guidance on when to use the tool ('Use when you discover something worth carrying forward') with concrete examples (ticker, address, preference). It explicitly mentions pairing with recall and forget, giving clear usage context and alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds meaningful context: internal cascading through multiple lookup endpoints, auto-disambiguation, and citation URIs. This goes well beyond what annotations provide.

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

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

The description is long but well-structured with examples, supported types, and return details. Each sentence adds value, though slightly verbose. Not as concise as the TDQS 4.3 example, but effective.

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

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

No output schema exists, so the description fully explains return values for each entity type, including citation URIs. Given the tool's complexity (multiple types, input variants, cascading lookups), it is complete and self-contained.

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

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

Schema coverage is 100% with detailed examples for both parameters. The description adds minor nuance (auto-disambiguated) but does not significantly go 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 the tool resolves names to canonical identifiers (ticker, CIK, RxCUI) and provides multiple example queries. It distinguishes itself from siblings by positioning it as the entry point for converting a name to an ID needed by other tools.

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

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

Explicitly guides when to use: 'Use FIRST whenever you have a name but need an ID.' Also notes it replaces 2-3 manual lookups. However, it does not explicitly mention when not to use or name alternatives, so it falls short of a 5.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds value by revealing that the tool internally calls ai_visibility_check for each entity, ranks scores, and returns a ranked list with score, confidence, and signal density per entity, providing concrete behavioral context beyond annotations.

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

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

The description is three efficient sentences: purpose, mechanism with output details, and a use-case example. Every sentence earns its place and the primary function is front-loaded.

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

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

Given the lack of an output schema, the description effectively specifies the return format (ranked list with score, confidence, signal density). It also covers mechanism and use case, making it complete for a read-only comparison tool with moderate complexity.

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

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

The schema covers 100% of parameters with detailed descriptions, including the entities array first-entry-as-subject convention and the models/_apiKey behavior. The description does not add new parameter semantics, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: comparing AI visibility across multiple entities side-by-side. It further details that it probes each entity with ai_visibility_check, ranks by score, and surfaces which is most/least recognized, distinguishing it from the single-entity sibling ai_visibility_check.

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

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

It provides clear context for competitive AI-marketing audits with an illustrative example question. However, it does not explicitly name alternative tools or when not to use this tool, though the multi-entity framing implicitly distinguishes it from single-entity checks.

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

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

Beyond the readOnly/idempotent annotations, the description adds critical behavioral context: it fans out to two external services, bundlephobia's first measurement can take 5-30s, partial failures degrade gracefully, and sources_failed will list timed-out sources. This discloses latency and failure behavior that annotations do not convey. 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?

Despite being a long paragraph, every sentence earns its place: purpose, service sources, usage triggers, output fields, ecosystem scope, and failure behavior are each covered without redundancy or filler. The organization is logical and efficient for a complex tool.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It enumerates all key return fields (is_latest, license, advisory_count, bundle_kb_gz, dependency_count, etc.), explains the alternative-versions list, and covers partial failure semantics. It is fully self-contained for an agent to invoke and interpret results correctly.

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

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

The input schema already has 100% coverage: both 'package' and 'version' have descriptions, including the defaulting behavior for version. The tool description adds only minor clarifications (scoped packages accepted, NPM only) but does not materially extend parameter semantics beyond the schema, so the baseline 3 is appropriate.

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

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

The description opens with a specific composite check purpose ('should I add this npm package to my project') and names the exact external resources (deps.dev, bundlephobia). It clearly distinguishes itself from siblings by emphasizing this is the npm-package-decision tool, while other ecosystem checks are explicitly pointed to deps.dev:version.

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

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

Explicit usage triggers are given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states when NOT to use it (non-NPM ecosystems) and names the alternative (deps.dev:version directly). This is exactly the when/when-not guidance expected.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond these by specifying the return structure (id/name, title, organization, resources with resource_ids) and the intended downstream use with query_resource. This exceeds the baseline expectation.

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

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

The description is two concise sentences that front-load the action and resource. Every part adds value: the search function, the data source, the return fields, and the linkage to query_resource. No redundant wording.

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

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

For a simple read-only search tool with optional parameters and no output schema, the description effectively communicates return structure and workflow. Combined with the rich annotations and schema, it provides complete guidance for an agent to select and invoke the tool correctly.

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

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

Input schema description coverage is 100%, with clear descriptions for query, limit, and offset. The description adds no parameter-specific semantics beyond what the schema already provides. 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 uses a specific verb ('Search') with a clear resource ('Finland Open Data datasets') and distinguishes itself from siblings by explaining that it returns resource IDs for use with query_resource. It clearly states the scope (by keyword) and output fields, making its purpose unambiguous.

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

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

The description provides clear context that this tool is for discovering datasets and obtaining resource_ids to be used with query_resource, implying a workflow. It doesn't explicitly exclude alternatives, but the linkage to query_resource effectively guides usage. A 5 would require explicit 'when not to use' or direct alternative naming.

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 a safe read-only, idempotent operation, but the description goes well beyond by disclosing the embedding model, windowing strategy (500-char overlapping windows), the 200K character cap, truncation flagging, and that results include offsets and similarity scores. This gives the agent a precise mental model of behavior.

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

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

The description is dense but well-structured: core action first, use case second, implementation technicalities last. It is somewhat longer than necessary, but every sentence contributes critical operational nuance, such as the cap and pairing with a sibling tool. The front-loading and logical flow are strong.

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

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

The tool has no output schema, so the description must explain return values—and it does, noting top-N passages with character offsets and similarity scores. It also addresses edge cases (truncation, 200K cap), provides a workflow suggestion, and covers parameter semantics comprehensively. Given the moderate complexity, this is complete.

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

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

All three parameters are already described in the schema, so baseline is 3. The description adds meaningful extra context by explaining that 'text' should be a fetched record, characterizing 'query' as natural language with examples, and reinforcing the truncation behavior tied to the text size. This elevates it above the baseline.

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

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

The description uses a specific verb phrase 'semantic search INSIDE a fetched record' and clearly identifies the resource and action. It distinguishes itself from siblings by emphasizing the 'fetched record' precondition and the offset+similarity output, setting it apart from broader tools like ask_pipeworx_grounded.

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

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

The description explicitly states when to use this tool: when the record is too big to fit in the prompt, to save context, and to return only relevant passages. It also names the complementary sibling (ask_pipeworx_grounded) and prescribes the fetch-then-search workflow, giving clear usage guidance.

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

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

Annotations indicate readOnlyHint=false and idempotentHint=true, and the description aligns with the write action. It adds valuable non-schema behaviors: phone verification requirement, SMS cap, webhook auto-disable after 10 failures, and one-time signing secret, all beyond annotations.

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

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

The description is long but information-dense; it is front-loaded with purpose and contains no filler. Could be restructured into sections, but every sentence earns its place given the complexity of the subscription setup.

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 clearly states the return value, covers all five subscription types, delivery channels, and operational caveats (phone cap, webhook failure policy). It thoroughly addresses the tool's complexity.

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

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

Even though schema coverage is 100%, the description adds concrete examples for each subscription type and clarifies delivery constraints like E.164 validation, verified phone, and webhook HMAC signing. This goes well beyond the schema's field descriptions.

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

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

Description clearly states the verb (Create) and resource (proactive monitoring subscription), and explicitly mentions the return value (new subscription id). This distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides explicit prerequisites (Pipeworx OAuth account required; anonymous/BYO cannot persist) and details supported subscription types. It doesn't explicitly name sibling alternatives for when to use vs list/unsubscribe, but the context is clear enough for tool selection.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is clear. The description adds valuable behavior beyond annotations: it returns category-bucketed examples, drawn from the live catalog, each with tool+argument shape. This gives concrete expectations about output content and source.

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 structured: starts with user query examples, explains return value, then usage. Each sentence adds value. It is longer than necessary but not wasteful, and the opening question phrases immediately convey the tool's purpose.

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

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

For a simple tool with one optional param, no output schema, and strong annotations, the description covers purpose, usage, parameter behavior, and output structure. It does not specify pagination or truncation of results, but for an onboarding suggestion tool this is not a significant gap.

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

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

Schema description coverage is 100% for the single optional 'topic' parameter, including allowed values and omission behavior. The description reinforces this with examples ('finance', 'pharma', 'betting') but does not add new semantic details 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's role as the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape to answer them. It distinguishes itself from siblings like ask_pipeworx and discover_tools by focusing on 'what to ask' rather than executing a query or listing tools.

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

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

Explicitly instructs to 'Use this FIRST when you do not yet know what Pipeworx can do for you', and mentions learning how to call meta-tools, providing clear context for when to use it. Also explains the optional topic parameter to focus results, giving both default and targeted 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?

The description goes well beyond annotations by disclosing that the row is deactivated, not deleted, and that historical events remain available via recent_alerts. This adds valuable behavioral context that annotations (such as destructiveHint=false) do not fully capture. There is no contradiction with annotations; in fact, it reinforces them.

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

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

Two sentences, front-loaded with the main action, then compactly conveying ownership and deactivation behavior. Every sentence earns its place, with no redundancy or filler.

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

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

The tool is simple (one parameter, no output schema), and the description covers what it does, the ownership constraint, the non-destructive nature, and the impact on recent_alerts. With annotations providing safety profile, this is a complete and self-sufficient 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?

The input schema already provides a description for the only parameter ('Subscription id (uuid) returned by subscribe.'), and schema coverage is 100%. The description doesn't add additional parameter semantics beyond restating that it's by id. Per the guidelines, baseline 3 is appropriate when schema covers all parameters.

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

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

The description starts with a specific verb and resource: 'Cancel a subscription by id.' This clearly distinguishes it from sibling tools like subscribe (which creates) and list_subscriptions (which lists). It also adds scope and behavior details (ownership, deactivation) that further differentiate it.

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

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

The description implies when to use the tool: to cancel a subscription. It also provides a key condition ('Ownership is enforced — you can only cancel your own subscriptions') and explains the effect on historical data. While it doesn't explicitly name alternatives or exclusions, the purpose is clear enough for an agent to decide appropriately.

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

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

Annotations declare readOnlyHint and idempotentHint, and the description does not contradict them. It adds behavioral context by detailing the SEC EDGAR + XBRL fast path vs the grounded pipeline, output verdict categories, and citation style. However, it does not disclose potential limitations like source availability or timeouts, so a 4 is appropriate given annotation coverage.

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

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

The description is about 120 words, longer than average, but every sentence adds value: trigger phrases, routing logic, output summary, and efficiency claim. It is front-loaded with examples and flows logically, though the initial string of quoted phrases is slightly repetitive. A 4 reflects that it is appropriately detailed without being wasteful.

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 comprehensively covers return values: specific verdict types, grounded/structured value with citation, and reasoning. It explains when each pipeline is used and what the output looks like, making it complete enough 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%, but the description adds significant meaning: for tolerance_pct it explains default behavior ('capped at 5') and suggests values for hallucination detection. For claim, it provides concrete examples, enriching the schema's own parameter descriptions.

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

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

The description clearly identifies the tool's function: natural-language claim verification against authoritative sources. It opens with example user phrases ('Is it true that…', 'fact check') and explicitly states the tool checks whether something a user said is factually correct, distinguishing it from sibling tools like ask_pipeworx or 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?

Provides explicit guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further specifies routing logic for company-financial claims vs all other factual claims, and notes it replaces 4–6 sequential calls, indicating when this tool is the preferred one-stop option.

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