Data Va

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable behavioral context beyond annotations: default model choice (Workers AI Llama-3.3-70b, free), cost implications (BYO Anthropic key with direct payment), and the detailed return structure (score, confidence, signals, raw_response, combined view). No contradiction exists.

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

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

The description is three sentences, front-loaded with the core purpose, followed by configuration details and use cases. Every sentence contributes essential information without redundancy or fluff.

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

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

Despite lacking an output schema, the description explicitly states the return format (per-model object with score, confidence, signals, raw_response, and combined view), covers all parameters (entity, models, _apiKey, context), and lists common usage scenarios. It is complete for a simple read-only probe tool with four parameters.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context by explaining that workers-ai is the free default and that providing an _apiKey enables Anthropic, with associated direct costs. This clarifies the models and _apiKey parameters beyond the schema 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 function: probing one or more LLMs for what they know about an entity and scoring visibility (0-100) per model. It uses specific verbs and resource types (business/brand/product/topic) and clearly differentiates from sibling tools by focusing on AI visibility scoring with use cases like competitive monitoring.

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 usage context: default free model, optional Anthropic with BYO key and direct payment, and typical use cases such as AI-marketing audits, pre-launch checks, and competitive monitoring. It does not explicitly name alternative tools or exclusion criteria, but the context is sufficient for an agent to decide when to invoke this tool.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. The description adds behavioral context: routing across 5,564 tools, argument filling, stable citation URIs, and that it works on every tier. It doesn't contradict annotations, but could mention potential response size or latency.

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

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

The description is longer than average but each sentence serves a purpose: directives, domain list, examples, alternatives, and context. It is front-loaded with the most important instruction ('PREFER OVER WEB SEARCH') and remains focused despite its length.

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

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

Given the tool's complexity (router across 5,564 tools), the description covers use cases, alternatives, input style, and return format (structured answer with citations). It doesn't explain output schema or rate limits, but with no output schema defined, the description's detail is adequate and complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100% with aliases clearly described. The description adds semantic guidance via concrete examples of acceptable questions (e.g., 'current US unemployment rate', 'Apple's latest 10-K'), which helps the agent understand the expected input format beyond generic schema text.

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: routes questions to appropriate data source tools and returns structured answers with citations. It explicitly distinguishes from alternatives like ask_pipeworx_grounded and deep_research, and from web search, providing a specific verb-resource relationship.

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

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

Description gives explicit 'prefer over web search' guidance and enumerates trigger phrases and domains. It tells when to use this tool versus ask_pipeworx_grounded and deep_research, and even covers the breaking-news edge case.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses that this is an experimental edge with candidate routing improvements that may be enabled live, and results are compared against stable to inform merges. It also clarifies it is a full working router, not a fallback stub. This adds significant 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 sentences and each adds value: purpose, current state, and usage guidance. It is slightly longer than the minimal example but remains focused and well-structured, with no wasted words.

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

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

The description covers the tool's role, current equivalence to stable, and experimental nature. It references ask_pipeworx for response shape, which is adequate given no output schema. It does not detail what the universal router does in general, but that is implied by 'universal router' and sibling context, making it sufficiently complete for 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 schema has 100% coverage with each parameter described as an alias for 'question', and the description only says 'same arguments' without adding parameter-level detail. Since the schema already fully explains the parameters, the description adds no extra meaning beyond referencing that they match ask_pipeworx, so the baseline 3 applies.

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

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

The description clearly states this is a beta version of ask_pipeworx, a universal router, and explicitly distinguishes it from the stable sibling ask_pipeworx. It mentions the same tool count, arguments, and response shape, making its specific role and difference 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 explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and compares with the stable router to decide merges. It also notes that currently no candidate is active, so it matches ask_pipeworx exactly, providing clear when-to-use guidance and implicitly contrasting with stable alternatives.

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

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

The description discloses key behaviors beyond annotations: it only extracts from the tool result, returns a refusal with specific reasons when data doesn't answer, and costs an extra LLM call. Annotations already declare readOnly/idempotent, but the description adds valuable refusal semantics and performance tradeoffs, with no contradiction.

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

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

The description is dense but well-structured, front-loading the purpose and then detailing process, failure modes, and usage guidance. Every sentence adds value: the refusal reason list and cost tradeoff are essential, not 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?

Despite the absence of an output schema, the description explicitly defines the success return shape and all possible refusal reasons. It also differentiates from sibling tools and addresses context (high-stakes reads, cost implications), making it complete for an agent to decide and invoke correctly.

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

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

Schema coverage for parameters is 100% and the schema describes the 'question' parameter clearly (including aliases). The description mentions that the tool 'fills arguments' but does not add meaning beyond the schema. Per the rubric, baseline 3 is appropriate when schema carries the heavy lifting.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' clearly stating the tool's purpose and differentiating it from the sibling ask_pipeworx. It explains the routing and extraction behavior, leaving no ambiguity about what the tool does.

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

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

The description explicitly says when to use this tool ('whenever an answer will be quoted, cited, or acted on') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'). It also names the alternative tool directly, providing clear triage guidance.

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

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

The annotations already mark the tool as readOnly/idempotent/non-destructive, and the description adds substantial operational behavior: low-confidence short-circuiting with status codes, closed-market handling, wide-spread illiquidity flags, news fallback details, and cancellation-rule risks. No contradiction; this exceeds what annotations disclose.

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 intentionally structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.), and it front-loads the core purpose. Every section provides concrete operational detail that is not available elsewhere, but the volume could overwhelm an agent and some examples are expansive.

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

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

This is a complex tool with no output schema, and the description compensates thoroughly: it documents the resolver contract (match confidence, alternatives, suggestions), parent event extraction, news fallback fields, blocking statuses, and cancellation-rule semantics. It gives an agent everything needed to interpret and safely use the response.

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

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

The input schema covers all three parameters with descriptions and 100% coverage, so the baseline is 3. The description adds context about the market input formats and fan-out behavior but does not materially elaborate on depth or include_raw beyond their schema definitions.

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

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

The opening sentence identifies the tool's core action ('Research a Polymarket bet'), the input forms (slug, URL, question), and output (evidence packet + comparison), making it clear how it differs from sibling market tools. The explicit 'Use for' examples reinforce its intended use.

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

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

Description gives concrete invocation contexts: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It explains blocking paths and safety checks, but does not name alternative tools or state when not to use it, leaving some ambiguity relative to sibling Polymarket tools.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description reveals data sources (SEC EDGAR/XBRL for companies; FAERS/FDA for drugs), off-calendar fiscal year handling, sorting by primary metric, and return format (paired data + pipeworx:// citation URIs). This rich behavioral disclosure far exceeds the baseline and aligns with annotations.

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

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

The description is a single dense paragraph with a logical flow: example queries, core purpose, preference rule, type-specific behaviors, sorting, and return details. Every sentence adds useful information with no filler—it earns its length.

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

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

With no output schema, the description fully compensates by explaining return format, data sources, sorting, and the efficiency benefit (replaces 8–15 lookups). It leaves no critical gaps 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%, so the baseline is 3, but the description adds meaning by tying the 'type' parameter to specific data sets and explaining that results are sorted by primary metric. It doesn't simply repeat schema descriptions; it adds context about how parameters affect output and behavior.

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

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

The description clearly defines the tool as performing side-by-side comparison of 2–5 companies or drugs in one parallel call, with specific query examples ('X vs Y', 'rank these companies'). It explicitly distinguishes from sequential single-pack lookups, making the purpose unambiguous and differentiating it from siblings like entity_profile.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides trigger examples. This sets a clear when-to-use rule and names the alternative approach (sequential lookups), satisfying the highest bar for usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds behavioral context by specifying the return fields and the recommended follow-up action (pass resource_id to query/metadata), which goes beyond the annotations and helps the agent understand the tool's role in a larger workflow.

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

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

The description is a single, well-structured sentence that front-loads the primary action and resource. It includes essential return fields and a clear follow-up instruction without any fluff or repetition of schema information. Every word earns its place.

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

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

Given the tool's simplicity (3 optional parameters, full schema coverage, and strong annotations), the description is complete. It explains what the tool does, what it returns, and how to proceed with the results. The absence of an output schema is compensated by the explicit list of return fields, making the tool's behavior well-understood.

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 for all three parameters (query, limit, offset) with 100% coverage, so the baseline is 3. The description does not add any parameter-specific meaning beyond the schema; it only mentions keyword search, which is already captured in the query parameter description. Therefore, the description adds no extra semantic value.

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

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

Description clearly states the tool's action: 'Search the Virginia Open Data catalog of open datasets by keyword.' It specifies the resource (Virginia Open Data catalog), the verb (search), and the output (resource_id, name, description, category, update date). It distinguishes itself from sibling tools by directing the agent to pass the resource_id to query/metadata for further operations.

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

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

The description provides explicit usage guidance: use this tool to search datasets by keyword, then pass the returned resource_id to query/metadata. This tells the agent when to use this tool (discovery) and what to use next, effectively identifying an alternative workflow. It does not explicitly mention 'when not to use' but the follow-up instruction is clear enough.

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

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

Adds substantial behavioral context beyond annotations: latency expectations (15-60s, up to ~90s), gap recovery behavior, contradictions[] flagging, excerpting strategy, and citation availability rules. Annotations already indicate read-only/idempotent, but the description enriches with operational details.

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

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

The description is long but information-dense, with every sentence serving a purpose (account, scope, decomposition, findings, alternatives, limitations, behavior, latency). It is front-loaded with the most critical info (account requirement, alternatives) and well-organized, though slightly verbose.

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 informs the agent of what to expect: findings packet structure (verbatim evidence, confidence, source, citation), gaps[], contradictions[], and hop fields. It covers limitations, alternatives, and operational nuances, making it complete for a complex multi-tool orchestrator.

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

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

Schema already covers parameters with detailed descriptions (coverage 100%), including enum values for depth. The description reinforces and adds context about depth's impact on hops and contradictions, which goes slightly beyond the schema's explanation.

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: 'grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' with explicit examples and distinguishes it from sibling tools like ask_pipeworx for single lookups. It uses a specific verb+resource and explains the decomposition/routing mechanism.

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 ('best for broad/multi-part questions over structured data') and when-not-to-use ('For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'), along with alternatives and account requirements. This is textbook guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds meaningful behavioral detail: it returns top-N relevant tools with names, descriptions, and full input schemas with curated examples, and each result is ready to call directly—no second schema lookup needed. This goes beyond the structured annotations.

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

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

The description is front-loaded with a clear purpose sentence and organized into purpose, use-cases, return behavior, and usage guidance. The domain list is a bit long but relevant for matching user intents, and every sentence contributes useful information without redundancy.

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

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

With no output schema, the description compensates by clearly explaining the return format (tool names, descriptions, full schemas, curated examples) and that results are ready to call. It covers input, use context, and output behavior sufficiently 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 description coverage is 100%, so the parameters are already well-documented. The description reinforces that query is a natural-language task description and mentions 'top-N,' which aligns with the limit parameter, but it does not add new semantics beyond what the schema provides.

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

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

The description states 'Find tools by describing the data or task' with a clear verb and resource. It distinguishes itself from sibling tools by emphasizing discovery/browsing rather than executing a query, and explicitly says 'Call this FIRST when you have many tools available and want to see the option set.'

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 use cases ('browse, search, look up, or discover what tools exist') and a strong directive to call this first in many-tool scenarios. It does not explicitly list when not to use it, but the context is sufficient to differentiate from direct query tools.

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

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

Beyond readOnly/openWorld annotations, description discloses data sources (SEC EDGAR, XBRL, USPTO, GDELT→GNews, GLEIF), fallback behavior, patent API sunset soft-fail, and return structure. 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?

Dense but front-loaded with examples; every sentence adds useful context (usage, sources, output specifics, constraints) without fluff.

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

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

With no output schema, description enumerates all return components (cik, filings, fundamentals, patents, news, LEI) with details like file limits and fallbacks, making invocation expectations clear.

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

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

Schema already covers both parameters fully (type enum, zero-padded CIK, names not supported). Description repeats this info but adds no new semantic meaning beyond schema.

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

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

Description opens with concrete user queries and then states 'full cross-source profile of a US public company' in ONE parallel call, distinguishing it from single-source lookups and sibling tools like resolve_entity/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?

Explicitly instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and tells users to 'use resolve_entity first if you only have a name', covering both when-to-use 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 destructiveHint=true, readOnlyHint=false, and idempotentHint=true, covering the safety profile. The description adds minimal extra behavioral context beyond 'clear sensitive data' and doesn't disclose error handling or permanence details. With annotations, this is acceptable but not additive.

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

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

The description is three short sentences with the action stated first. No filler; each sentence contributes purpose, usage timing, and complementary tools, making it tightly 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 one-parameter destructive operation with a clear schema and annotations, the description covers what, when, and related tools. It lacks return-value or error details, but these are not critical for this simple tool, making it adequately complete.

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

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

The input schema fully documents the single 'key' parameter with 100% coverage, including an example. The description merely repeats 'by key' without adding new semantic details, so it doesn't add value beyond the schema.

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

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

The description opens with 'Delete a previously stored memory by key', clearly stating the verb (delete), resource (memory), and key-based method. It distinguishes itself from siblings like remember and recall by explicitly describing the deletion operation.

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

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

The description gives explicit usage scenarios: 'context is stale, the task is done, or you want to clear sensitive data'. It also says 'Pair with remember and recall', providing direct alternatives and complements, making when-to-use guidance very clear.

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

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

Annotations already mark the tool as read-only, non-destructive, and idempotent, so the description need not repeat that. It adds transparency by describing the process (fetch/extract/emit) and the output format (single text blob at site-root/llms.txt), giving agents a fuller behavioral model.

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

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

The description is three sentences, front-loaded with the main purpose, followed by concrete use cases and the output format. Every sentence contributes value, 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?

Given the simple 2-parameter schema and rich annotations, the description adequately covers the tool's behavior, use cases, and output. Since there is no output schema, the explicit mention that the output is a ready-to-drop markdown blob is essential and well provided.

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

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

Schema coverage is 100%, with both parameters (url and max_links) well described in the schema. The description does not add much parameter-specific detail, but that is unnecessary given the schema's thoroughness, so baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file from a URL, with specific actions: fetches the page, extracts title/description/key links, and emits standard markdown. This unambiguous verb+resource combination distinguishes it from sibling tools like scan_competitor_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 'Useful for' list provides explicit use cases (client indexing, drafting, competitor audit), guiding an agent on when to apply the tool. It does not mention when not to use it or alternatives, but the context given is clear enough for decision-making.

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?

With annotations already declaring readOnlyHint, idempotentHint, and destructiveHint false, the description adds value by specifying the return fields and the optional include_inactive behavior. It does not contradict annotations and provides context beyond the structured data.

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

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

Two sentences, front-loaded with the action, and every clause carries useful information. No fluff 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 list tool with one optional parameter, the description covers purpose, return shape, and use cases. Annotations provide safety/behavioral guarantees. The lack of an output schema is compensated by enumerating return fields.

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 single parameter include_inactive is fully described in the schema (100% coverage). The tool description does not add additional parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

Clearly states 'List the caller's active subscriptions' which is a specific verb+resource. It also describes the returned fields, making the purpose concrete. Though it doesn't explicitly contrast with sibling tools like subscribe/unsubscribe, the resource is unambiguous.

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

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

The description explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel,' giving concrete when-to-use scenarios and implying alternatives (subscribe/unsubscribe). This is excellent 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 mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds what data is returned (schema, columns, types, row count, category, last-updated), which is useful behavior context beyond the annotations. No contradiction.

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

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

Single sentence with an example, no filler. Effectively front-loaded and every clause adds value.

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

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

For a one-parameter retrieval tool with strong annotations and full schema coverage, the description explains the return content and the required input. It is complete for its scope, and no output schema is needed.

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

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

The input schema already fully describes resource_id with the same example and coverage is 100%. The description adds no new parameter semantics beyond what the schema provides, so it meets 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 ('Get') and identifies the exact resource ('a Virginia Open Data dataset's schema + metadata') with the fields returned (columns, types, row count, category, last-updated). The example resource_id adds clarity and distinguishes this from sibling tools like 'datasets' or 'query'.

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

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

The description clearly implies this tool is for retrieving structural metadata by resource_id, and the example shows how the ID looks. However, it does not explicitly state when to prefer this over sibling tools like 'datasets' or 'query', so it lacks explicit alternatives/conditions.

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, providing no safety or behavioral profile, so the description carries full burden. It discloses rate-limiting (5 per identifier per day), quota exemption, the claim_token two-step flow, and that feedback is read daily and affects roadmap—details well beyond the schema.

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: purpose, exclusions, token mechanics, rate limits, and roadmap impact. Front-loaded with the main action, it avoids redundancy and remains scannable despite multiple clauses.

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

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

Given the tool has 4 params (one nested), no output schema, and a non-trivial claim_token workflow, the description covers the entire lifecycle: when to file, what to include, what is returned (claim_token), how to follow up, and ancillary constraints (rate limit, quota). It leaves no significant behavioral gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds valuable semantics: the claim_token callback syntax, the instruction to frame issues in terms of Pipeworx tools/packs rather than pasting user prompts, and the optional context object's relationship to the issue. It doesn't redefine parameters but enhances practical usage.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates exact use cases (bug, feature, data_gap, praise) and draws a clear boundary against other MCP servers, fully distinguishing it from sibling research/query tools.

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

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

The description explicitly states when to use (bug, feature/data_gap, praise) and when not to use (issues with non-Pipeworx MCP server tools), and even suggests an alternative action: 'file it with that server instead.' It also clarifies identification of Pipeworx tools by the connection listing.

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 (readOnly, openWorld, idempotent, non-destructive), the description discloses important behavioral details: data source ('derived from CF analytics-engine'), privacy ('no PII'), result shape ('just (pack, tool, count)'), and caching ('Cached 5min-1h depending on window'). This adds significant transparency.

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 yet information-dense, using three sentences to cover purpose, use cases, and technical details. The colon-separated list is easy to parse, and no sentence is wasted.

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

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

For a simple one-parameter tool with no output schema, the description covers everything: what it returns, when to use it, data source, caching, and privacy. It gives a complete mental model without requiring additional context.

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

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

Schema coverage is 100% and the enum values are already described in the schema. The tool description adds further semantic guidance by explaining trade-offs: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps agents choose the right window.

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

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

The description opens with a clear statement of what the tool does: 'What other AI agents are calling on Pipeworx right now' and lists the exact outputs (top tools, top packs, total call volume). It distinguishes itself from sibling tools like discover_tools by focusing on real-time aggregated usage trends rather than tool discovery.

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

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

The description provides a 'Useful for' section with three explicit use cases, giving clear context for when to use the tool. It does not name alternative tools or exclusion conditions, but the use cases are specific enough to guide selection.

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

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

Beyond annotations, the description discloses fill-check behavior (realizable_edge_pp <= 0 means don't trade), partition-filter placeholder logic, and semantic-anchor Jaccard similarity, giving critical behavioral context for evaluating results. It also describes response structures and limitations (skipped_low_similarity, placeholders_filtered).

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

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

The description is dense and every section adds value, but it's a long unbroken text block that could benefit from bullet points. It front-loads the core function but is exhaustive, which is justified for a complex tool with multiple modes.

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

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

With no output schema, the description fully documents the response shape (opportunities[], partition_check{...}, fill_check details) and references related tool for sizing, making it complete and actionable for an agent.

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

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

Although schema covers both params, the description enriches meaning: explains 'event' accepts slugs or full URLs, describes partition_check output, and contrasts event vs topic modes. This goes far beyond the schema's short descriptions and clarifies the distinction between the two optional arguments.

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 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks,' providing a specific verb, resource, and methodology. It clearly distinguishes this tool from siblings like polymarket_edges by detailing its unique modes (trending_scan, event, topic) and how they differ.

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 tells when to use each mode: 'Call with NO args for a trending_scan... pass event for... or topic for...' and 'For custom sizing use polymarket_fill_risk.' It also notes when topic is preferable over event for cross-event patterns, and even differentiates from the fill_risk sibling.

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 establish read-only, idempotent, non-destructive behavior, but the description adds substantial context beyond that: 1-hour KV caching keyed on knobs, segment-level responses, diagnostics for empty segments, Fed-signal reliability caveats, and edge calculation details (slippage, Kelly caps, 24h-move warnings). No contradiction with annotations.

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

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

The description is front-loaded and organized with labeled sections, but it is very long and includes non-essential implementation minutiae such as per-sport alpha values and specific gate changes ('Run 8 from prior 85%/5%/50:1'). It reads more like a behavioral specification than a concise tool doc, so it does not earn a 4 or 5.

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

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

With no output schema, the description carries the full burden of explaining return values and does so thoroughly: it lists top-level response fields (by_segment, fed_candidates/fed_note, _diagnostics), explains why segments can be empty, documents edge fields, and notes caching behavior. For the complexity of the tool, the operational context 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?

Even though schema description coverage is 100%, the description layers meaningful context onto the parameters: min_liquidity/max_spread_pp as tradeable-edge filters, min_partition_leg_kelly's special per-leg behavior, and slippage being netted before ranking/Kelly. This goes well beyond the baseline provided by 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 first sentence states a specific action ('Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price') and names the exact resource and output. It also frames the use case as 'what should I bet on today', which clearly distinguishes it from generic market queries or arbitration-specific 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?

The description gives clear usage context ('agents discover opportunities without paging hundreds of markets') and explains what knobs adjust. It does not explicitly contrast with sibling tools or state when not to use it, so it lacks the when-not/alternatives detail needed for a 5.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses significant behavioral details: snapshots are written only on cache-miss, gaps mean no scan that day, history bounded by 60-day TTL, decay based on daily closes not intraday, and response structure includes expired opportunities and median lifespan. This fully enriches the agent's understanding.

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

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

The description is well-structured with clear sections: purpose, args, response, and limits. It is dense but every sentence contributes useful information. Front-loaded with the core question, making it immediately clear what the tool does.

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

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

Given no output schema, the description thoroughly explains the response format (tracked[], expired[], snapshot_dates[]) with field meanings. It also covers limitations (TTL, start time) and operational behavior (cache-miss gaps). The tool is simple (2 params) and the description is fully sufficient for correct invocation and interpretation.

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

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

Schema coverage is 100%, but the description adds value by specifying defaults (days default 14, max 30; window default '1wk') and clarifying 'window' as a snapshot family. This goes beyond the schema's basic descriptions, enhancing parameter understanding.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' and answers the specific question 'how long has this edge existed and is it shrinking?'. It distinguishes itself from sibling polymarket_edges by focusing on time-series snapshots rather than current edges, making it a unique and specific resource.

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 this tool via its core question ('how long has this edge existed and is it shrinking?') and the contrast with a 'fresh wide edge' vs a '3-week-old wide edge'. However, it does not explicitly name sibling tools as alternatives or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral detail: it 'walks the ladder' and returns specific fields like verdict (clean|degraded|cannot_fill), explains basket mode's forced_directional_risk, and warns that partial basket fills convert an arb into an unhedged directional position. It also clarifies how size_usd is interpreted differently across modes.

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 heavily structured with SINGLE-MARKET / BASKET / USE THIS sections, and every sentence adds a distinct piece of information (return fields, risk warnings, parameter interpretation). No filler or repetition. The length is justified by the tool's two modes and risk-critical usage, though it could be slightly tightened.

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 must cover return values; it does so exhaustively for both modes (top_of_book, vwap_fill_price, capture_ratio, thin_legs[], etc.). It also covers usage prerequisites, parameter constraints (clamp 10–1,000,000), and risk scenarios. The only minor gap is not defining some trading terms, but they are domain-standard and the description is otherwise 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% (all 4 params have descriptions). The description reinforces these but adds key context: 'REQUIRES one of market or event' (mutual exclusivity), default values (buy_yes, size_usd 1000), and mode-specific semantics (e.g., basket size_usd as settlement notional). This goes beyond the schema by clarifying the relationship between parameters and modes.

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 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' providing a specific verb ('check') and resource ('live CLOB order-book depth'). It clearly distinguishes two modes (single-market and basket) and contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by positioning itself as a pre-trade risk assessment.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' — naming exact sibling tools and thresholds. It also explains why (theoretical overround on thin books is not capturable, partial fills create unhedged directional risk), giving clear when-to-use and when-not-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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, and the description does not contradict these. It adds substantial behavioral context: compatibility_warning conditions (matched_pairs:0 with skipped_cross_type>0 vs skipped_cross_type:0), temporal_alignment implications, skipped_cross_type/subtype meanings, and the blunt warning that pre-mapped does not equal tradeable. This goes far beyond what annotations imply.

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 densely packed with necessary information. It is front-loaded with the core purpose, then logically flows through modes, response format, safety fields, and caveats. Every sentence earns its place by conveying a distinct behavioral or usage detail. No fluff or repetition exists; the structure helps the AI agent parse complex semantics efficiently.

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 fully compensates by detailing the response structure (leg-by-leg prices, matched spread[], top_spreads_pp), the precise conditions for compatibility_warning, and the meaning of temporal_alignment and skipped counters. It also addresses edge cases like both venues having >5 legs and semantic mismatches. The description is complete 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%, so baseline is 3. The description adds value by explaining the two modes and how explicit kalshi_event_ticker and polymarket_event_slug override the topic-mapped side. It also clarifies the list of valid topic strings and the meaning of overrides, which the schema descriptions only hint at. This elevates clarity beyond the schema alone.

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

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

The description clearly states it computes the 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This specifies the verb (compute/cross-venue spread), resource (Kalshi/Polymarket), and scope (same resolving question), distinguishing it from sibling tools like polymarket_arbitrage. It also details two modes and the response format, leaving no ambiguity about the tool's function.

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

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

The description provides explicit guidance on when to use the two modes (topic shortcuts vs explicit tickers) and explains when the spread is meaningful vs. when compatibility warnings indicate no arb exists. However, it does not directly name alternative tools or state 'use X instead of Y,' which would be needed for a perfect score. The caveats about pre-mapped topics being rarely tradeable offer practical usage boundaries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, so the safe read-only nature is covered. The description adds meaningful context: returns JSON, specific SoQL clause handling, and the requirement not to use leading $, which is 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?

Two sentences, front-loaded with the main purpose, including an example resource_id. Every word earns its place, and the structure is clean and direct.

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 states returns JSON. It covers all parameter groups (where, select, group, order, limit, offset, resource_id) and provides usage context. For a 7-parameter tool, this is complete and sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100% (all 7 parameters described). The description adds extra semantic value by explaining the SoQL clauses and the 'no leading $' convention, which is not obvious from the schema alone. This goes beyond 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 'Run a Socrata SoQL query' against a specific resource identified by resource_id, with an example. It distinguishes from siblings like 'datasets' (listing datasets) and 'metadata' by focusing on querying rows.

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 it: when you have a resource_id and need to filter/select data. It does not explicitly state alternatives or exclusions, but the context and syntax details (SoQL without leading $) provide clear guidance for use.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable context beyond annotations: it explains scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the behavior of listing all keys when the key is omitted. This is useful but doesn't cover return types or edge cases, so a 4 is appropriate.

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

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

Three concise sentences front-load the core action, then provide usage context and related-tool pairings. Every sentence earns its place—no waste, no redundant repetition of schema or annotations.

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

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

This is a simple one-parameter tool without an output schema. The description covers the full behavior (retrieve vs list), usage context with concrete examples, scoping rules, and relationships to sibling tools. Nothing essential is missing 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 the parameter 'key' described as 'Memory key to retrieve (omit to list all keys)'. The description adds a bit more meaning by explaining the key refers to values saved via 'remember' and ties into scoping, but it doesn't add substantial new syntax or format details beyond the schema. Hence baseline 3 applies.

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

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

The description clearly states the tool retrieves a value saved via 'remember' or lists all keys when the key is omitted. It distinguishes itself from sibling tools like 'remember' and 'forget' by explicitly naming them and framing actions around them.

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

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

The description provides explicit guidance on when to use the tool: to look up previously stored context such as a user's target ticker, address, or research notes, avoiding re-derivation. It also explains scoping to an identifier and how it pairs with 'remember' and 'forget', offering clear usage context.

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

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

The description discloses a mutating side effect (mark_read flags events read), but annotations declare readOnlyHint: true, which contradicts that behavior. Since the description contradicts the annotation's read-only claim, this violates the transparency rule. Flag as annotation 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?

Three sentences cover purpose, return contents, filtering options, side effect, and alternative access. No filler; front-loaded with the core action. Every sentence earns its place.

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

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

Covers return payload fields, filtering, side-effect behavior, and alternative access. Missing details on unread_only semantics or how it interacts with mark_read, and the readOnly annotation conflict creates ambiguity, but otherwise sufficient for a read 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 5 parameters with descriptions, providing a strong baseline. The description adds extra meaning by explaining mark_read's consequence ('next call only shows newer ones') and giving a concrete type example ('sec_8k'), enhancing the schema's minimal descriptions.

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

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

Description opens with 'Pull fired events from your subscription feed', a specific verb+resource statement. It clearly distinguishes this from sibling tools like list_subscriptions or recent_changes by focusing on alert events with payload details.

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?

Gives context by stating 'Polls work fine' and mentioning an alternative HTTP endpoint for scripts/dashboards, indicating when the tool is appropriate. However, it does not 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?

Beyond annotations (readOnly, openWorld, idempotent), the description discloses non-obvious behaviors: fan-out to multiple APIs, GDELT preferred with GNews fallback on rate-limits/5xx, and USPTO PatentsView sunset causing soft-fail. These are valuable operational details not inferable from annotations or schema.

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: examples, definition, source breakdown, fallback logic, parameter clarification, return structure, and alternative tool guidance. It is front-loaded with the most relevant info and avoids redundancy.

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

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

Despite lacking an output schema, the description explains the return structure (changes[] grouped by source, total_changes, citation URIs). Combined with the detailed source/fallback info and parameter semantics, it covers the tool's complexity comprehensively.

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 examples and clarifies that `since` accepts ISO dates or relative shorthand ('7d', '30d', '3m', '1y') and that `value` can be a ticker or CIK. This adds helpful context beyond the schema's own descriptions, warranting a 4.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months' and lists the fan-out sources (SEC EDGAR, GDELT/GNews, USPTO). It also distinguishes itself from sibling entity_profile by explicitly pointing to the alternative for static profiles.

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

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

It provides explicit usage context with example queries ('What's new with X'), describes the fallback behavior (GDELT→GNews), and gives a clear when-not-to-use directive: 'Use entity_profile instead when you want the static profile...'. This exceeds basic 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?

Adds valuable behavioral context beyond annotations: memory is 'scoped by your identifier', authenticated users get persistent memory, anonymous sessions retain memory for 24 hours. This clarifies storage semantics and complements the idempotentHint and destructiveHint annotations without contradiction.

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

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

The description is concise (three sentences) and front-loaded with purpose, followed by usage guidance and storage details. Every sentence adds distinct value with no redundancy or fluff.

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

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

For a simple two-parameter write tool with no output schema, the description covers purpose, use cases, storage scope, persistence, and related tools. Combined with clear annotations, it provides complete operational guidance with no significant gaps.

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

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

Schema description coverage is 100%, so the schema already documents both parameters with examples. The description reinforces the key-value pair structure but does not add significant new parameter-level semantics beyond what the schema provides, resulting in a baseline score.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later' with a specific verb and resource. It distinguishes from siblings by explicitly mentioning recall for retrieval and forget for deletion, making the tool's unique role obvious.

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

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

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples. It also contrasts with alternatives ('Pair with recall to retrieve later, forget to delete') and explains persistence differences between authenticated and anonymous sessions, giving clear decision context.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds significant behavioral context: internal cascading through multiple lookups, graceful degradation of LEI/FIGI enrichment, explicit listing of unresolved identifiers, and coverage of non-US issuers via ISIN. No contradictions with annotations.

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

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

The description is front-loaded with example queries, which is effective. While it is multi-paragraph and verbose, every sentence adds value (supported types, sources, fallback behavior). It is well-structured with clear sections for each entity type.

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

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

Without an output schema, the description fully explains what identifiers are returned (CIK, ticker, LEI, FIGI, etc.) and handles edge cases (ISIN input, graceful degradation). For a two-parameter tool, this is exceptionally complete.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by providing concrete examples for 'value' (ticker, CIK, drug name) and explaining how ISIN resolves to legal entity. This goes beyond the schema's brief descriptions.

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

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

The description starts with clear example queries ('What's the ticker for...') and explicitly states the tool resolves names to canonical identifiers. It differentiates from siblings by being the dedicated name-to-ID resolution tool, which is not done by any other sibling tool listed.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It does not explicitly list when not to use or mention alternatives, but the context is clear and sufficient for an agent to decide.

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

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

The description discloses that it probes each entity with ai_visibility_check, ranks by score, highlights most/least recognized, and returns score, confidence, signal density. This adds behavioral detail beyond the readOnlyHint/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?

Four concise sentences, front-loaded with the primary action, followed by method, use case, and return value. 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 tells the agent exactly what to expect: a ranked list with score, confidence, and signal density. Combined with 100% schema coverage and annotations, it's fully specified.

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 parameter descriptions. The description only paraphrases the entities parameter ('your brand + N competitors') and adds no new semantics for models or _apiKey.

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 'Compare AI visibility across multiple entities side-by-side', which is a specific verb+resource. It distinguishes from siblings like ai_visibility_check by emphasizing side-by-side comparison and ranking.

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 a clear use case: 'Useful for competitive AI-marketing audits' with an illustrative query. Implicitly contrasts with ai_visibility_check for single entity checks, but lacks explicit 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 already declare readOnly/openWorld/idempotent, and the description adds substantial behavioral context: fan-out architecture, partial failure degradation, bundlephobia timing (5-30s), sources_failed field, and return structure. This goes far beyond the structured annotations.

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

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

The description is dense but front-loaded with the core purpose, then use case, return fields, limitations, and failure behavior. Every sentence earns its place and is logically structured. Length is justified by the tool's complexity.

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

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

There is no output schema, so the description compensates with a detailed list of returned fields, timing, failure handling, and ecosystem scope. It fully covers the key context an agent needs for a composite read-only 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 the schema already describes both parameters. The description adds no additional parameter details beyond what the schema provides. Baseline 3 is appropriate per the rubric for high schema coverage.

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

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

The description clearly states a specific verb+resource+scope: 'Composite should I add this npm package to my project check in ONE call — fans out across deps.dev ... and bundlephobia'. It also explicitly limits to the NPM ecosystem, distinguishing it from any potential 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?

Explicit when-to-use guidance is given: 'Use whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. It also provides a clear when-not: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'.

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

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

Annotations already declare readOnly/openWorld/idempotent hints, so the bar is lower. The description adds substantial behavioral detail: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging, and output containing offsets and similarity scores. 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?

Four sentences, front-loaded with purpose, then usage, then technical details. Every sentence earns its place — no filler, no repetition of schema content. The structure flows logically from what → when → how.

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 compensates by explaining the return format (top-N passages, character offsets, similarity scores). It also covers edge conditions (200K truncation) and pairing with other tools. For a search tool with 3 simple params, this is complete.

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

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

Schema description coverage is 100%, so baseline is 3. All parameters (text, query, limit) are already well-described in the schema with examples. The description reinforces that 'text' is the already-fetched record and that query is natural-language, but adds no new semantic detail beyond what the schema provides.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' a specific verb+resource pair. It immediately distinguishes itself from siblings like ask_pipeworx or query by emphasizing this operates on already-fetched text, and it pairs with ask_pipeworx_grounded, clarifying its niche.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also describes the integration pattern with ask_pipeworx_grounded, giving a clear workflow. This provides both a use case and an alternative/companion tool, exceeding the minimum 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?

Despite annotations already indicating readOnly=false, openWorld=true, and idempotent=true, the description adds valuable behavioral context: the auth requirement and persistence constraint, the always-on feed behavior, the optional email/SMS channels with a 10/day SMS cap, and the need for phone verification. These details go beyond the annotations and help the agent anticipate side effects and 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 front-loaded with purpose ('Create a proactive monitoring subscription') and organized into coherent segments (purpose, auth, types, delivery). It is on the longer side, and some content (e.g., supported types and delivery details) overlaps with the schema, but every sentence adds relevant operational detail. Slightly tighter would be better, but it's not 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 the tool's complexity (3 params, nested objects, multiple subscription types, delivery channels) and no output schema, the description is quite complete: it covers purpose, return value, auth requirements, persistence, types, delivery options, feed access, and SMS limits. It omits webhook details (though the schema covers them) and doesn't explicitly address idempotency, but these are secondary. Overall, it provides a solid operational picture.

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

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

Schema description coverage is 100% and the schema itself is very detailed (e.g., params object with per-type patterns, delivery object with sms/email/webhook descriptions). The description adds some illustrative examples ('items:["5.02"] = officer change', 'params:{topic:"fed"}') but largely duplicates the schema. Baseline 3 is appropriate since the schema already carries 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 uses a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly distinguishes it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts, which are about managing or reading subscriptions/alerts.

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

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

The description provides clear context: proactive monitoring vs pull (mentions 'pull via recent_alerts or GET registry.pipeworx.io/alerts.json'), and explicit prerequisites ('Requires a Pipeworx OAuth account; anonymous + BYO cannot persist subscriptions'). It does not explicitly name alternative tools for one-off queries, 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context: it returns example questions with exact tool+argument shape drawn from a live catalog, and explains that calling with no arguments gives the full spread while a topic narrows it. This goes beyond what annotations provide, though it doesn't cover potential rate limits or output format details.

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

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

The description is longer than average but every sentence earns its place: it starts with natural language query examples, explains the output structure and source, covers the parameter usage, and gives explicit placement guidance. It is front-loaded and well-structured, only losing a point for length that could be trimmed slightly.

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 compensates by explaining exactly what is returned (category-bucketed example questions with tool+argument shapes). With one optional parameter, full schema coverage, and strong annotations, the description provides sufficient context for an agent to select, invoke, and interpret the tool correctly. No gaps remain.

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

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

Schema coverage is 100% and the schema already documents the optional topic parameter with allowed values. The description reinforces this by giving examples ('finance', 'pharma', 'betting') and clarifies the behavioral effect of omitting versus passing the parameter ('full spread' vs 'focus'), adding semantic value beyond the schema's dry list of enums.

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

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

The description clearly states the tool is an onboarding entry point that returns category-bucketed example questions for what to ask Pipeworx. It names a specific verb+resource ('returns category-bucketed example questions') and distinguishes it from siblings like ask_pipeworx by framing it as a meta-tool for learning how to call 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?

Explicit usage guidance is provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains how to call with or without the topic parameter, giving concrete examples of focus areas and alternatives (meta-tools) to learn about.

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 important behavioral traits: ownership enforcement (you can only cancel your own subscriptions) and that the row is deactivated, not deleted, preserving historical events. This adds significant value and is consistent with annotations (idempotentHint, destructiveHint false).

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

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

The description is concise: two sentences, action first, behavioral details second. Every sentence contributes meaning 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?

For a single-parameter cancellation tool with annotations, the description covers the action, ownership, and data retention implications. It is complete enough for an agent to select and invoke the tool correctly, and no output schema is needed.

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

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

Schema description covers the id parameter fully, but the description adds the ownership constraint that the id must be your own subscription, which is valuable parameter context. This goes beyond the schema's generic 'returned by subscribe'.

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 the specific verb 'Cancel' with the resource 'subscription by id', clearly stating the tool's function. It distinguishes from siblings like subscribe and list_subscriptions by focusing on the cancellation action.

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

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

The description provides clear context for when to use the tool (to cancel a subscription) and includes the ownership constraint. It mentions deactivation vs. deletion and historical events via recent_alerts, but does not explicitly name alternatives or when-not-to-use compared to siblings.

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

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

Beyond annotations, the description discloses internal routing logic (financial vs. other claims), the return structure (verdict, value, citation, reasoning), and critical behavioral caveats (could_not_verify means check did not happen, unsupported means no source). This adds substantial context that annotations do not cover, and it does not contradict any annotation.

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

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

The description is longer than typical but densely packed with valuable information. It front-loads trigger phrases and proceeds through routing, outputs, and caveats. Every sentence adds something, though some repetition of 'grounded' could be tightened. It earns a high score for effectiveness, but loses a point for slight verbosity.

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

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

Given the absence of an output schema, the description fully explains return values and their meanings, including the nuanced distinction between 'could_not_verify' and 'unsupported'. It covers edge cases, error handling, and the tool's overall role, making it complete 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 already documents both parameters (100% coverage), but the description adds meaningful semantics: tolerance_pct is explained as overriding the implied tolerance with practical guidance (set 1–2 for hallucination detection) and a default cap of 5. The claim parameter is illustrated with examples, enriching the schema description.

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

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

The description clearly identifies the tool as a claim verifier with specific verb ('verify') and resource ('natural-language claim against authoritative sources'). It distinguishes itself by describing the two distinct pipelines (SEC EDGAR for financial claims, grounded pipeline for others) and states it replaces multiple sequential calls, setting it apart from sibling tools.

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

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

Explicit guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further clarifies when the structured path vs. grounded pipeline applies, and explains the semantic difference between 'could_not_verify' and 'unsupported', preventing misuse. The alternatives (sequential calls) are implied via 'Replaces 4–6 sequential calls', but usage context is strong.

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