Vies Eu

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

The description adds meaningful behavioral context beyond the annotations: it reveals the default free model (Workers AI Llama-3.3-70b), explains that passing `_apiKey` incurs direct charges via Anthropic, and previews the return shape. Annotations already declare readOnly/openWorld/idempotent hints, and the description does not contradict them.

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

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

Three sentences cover purpose, configuration/cost, return format, and use cases. Every sentence earns its place, and the most important information is front-loaded. There is no fluff or repetition of schema content.

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

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

The description fully orients an agent: it explains what the tool does, which models are available, cost behavior, return structure, and common use cases. With no output schema, it still communicates the return shape (per-model {score, confidence, signals, raw_response} + combined view). Minor gap: no explicit 'when not to use' comparison, but overall complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents all 4 parameters. The description adds marginal but useful details: the exact default model name and the cost implication of `_apiKey` ('you pay Anthropic directly for those calls'). This goes beyond the schema's parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly states the tool's function and distinguishes it from sibling tools like scan_competitor_ai_presence by focusing on per-model visibility scoring for any entity, not just competitors.

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

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

The description explicitly lists use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' This provides clear context for when to use the tool. However, it does not explicitly contrast with sibling tools or state when not to use it, so it lacks full exclusion/alternative guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description does not contradict them. It adds useful behavioral context: returns structured answers with stable pipeworx:// citation URIs, works on every tier, and is fast (one call). It does not disclose potential limitations like rate limits or latency, but the annotations lower the bar, and the added context is meaningful.

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 the two-sentence ideal but every segment adds value: scope (data domains), usage pattern ('what is', 'look up'), examples, and alternative escalation paths. It is front-loaded with the priority directive 'PREFER OVER WEB SEARCH', making it scannable. Slight verbosity prevents a 5.

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

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

Given the tool's broad scope and lack of an output schema, the description comprehensively covers what it returns (structured answer with citation URIs), when to use it, and how it relates to sibling tools. It even addresses breaking news routing. The description is sufficient for an agent to invoke correctly without further 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 all parameters (including aliases) have descriptions in the schema. The description provides examples of questions but does not add new parameter-level semantics beyond what the schema already states. Per guidelines, baseline 3 is appropriate when schema covers details.

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

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

The description clearly states the tool routes questions to authoritative sources and returns structured answers with citations, using a specific verb (routes) and resource (5,529 tools). It distinguishes itself from sibling tools by naming ask_pipeworx_grounded and deep_research as alternatives, so it fully satisfies the differentiation criterion.

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 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', providing clear when-to-use guidance. It also names specific alternative tools with conditions (e.g., ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions), making usage instructions highly actionable.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: candidate routing improvements are 'enabled live' when under test, currently no candidate is active, and results are compared against the stable router. This clarifies runtime behavior and temporal semantics without contradicting annotations.

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

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

The description is three sentences, front-loaded with the core identity and relationship to ask_pipeworx, then status, then usage. While there is slight redundancy ('identical' vs. 'currently matches exactly'), each sentence serves a clear purpose and the overall structure is effective.

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

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

The tool has no output schema, and the description only references 'same response shape' without detailing what that shape is. However, given its simple parameter set and strong annotations, the experimental status, current behavior, and usage are adequately covered. The output remains implicit, which is a minor gap.

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

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

The input schema has 100% coverage: all six properties (question, q, text, input, query, prompt) are explicitly described as aliases. The description adds nothing beyond stating 'same arguments,' so the baseline of 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly states it is a 'Beta version of ask_pipeworx: identical universal router' with the same tools, arguments, and response shape, and explicitly labels it 'the experimental edge.' This distinguishes it from the stable ask_pipeworx and other siblings by highlighting its beta/experimental status and scope.

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

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

The description gives explicit when-to-use guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that 'results are compared against the stable router to decide what merges,' implying alternatives and exclusions. It also clarifies it is a full working router, not a fallback stub.

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, but the description adds significant behavioral context: the grounded extraction process, the explicit refusal reason vocabulary (not_in_source, no_tool_match, etc.), the verbatim evidence quote, and the extra LLM call cost. No contradiction with annotations.

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

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

The description is compact yet information-dense: it explains the mechanism, return format, refusal modes, usage context, trade-off, and sibling relationship in just four sentences. Every clause adds value with no redundant content or filler.

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

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

With no output schema, the description fully covers return values on both success and failure, including the refusal_reason enumeration. It also conveys the tool's scope (routing across 5,529 tools), the cost versus ask_pipeworx, and the high-stakes context, making it complete for an agent to judge invocation.

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

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

Schema coverage is 100% with all six parameters being aliases for the same 'question' parameter, and the schema already documents each alias. The description does not add parameter-specific meaning beyond what the schema provides, so the high-coverage baseline of 3 is appropriate.

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

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

The description clearly identifies this as a hallucination-resistant answer mode for high-stakes reads, with a specific verb ('EXTRACTS') and resource (answer grounded in tool results). It explicitly contrasts with the sibling ask_pipeworx tool by detailing the grounded extraction mechanism and refusal semantics, distinguishing it from casual lookups.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and lists specific high-stakes domains (financial, legal, medical, public statements). Also gives a clear when-not-to-use: 'prefer ask_pipeworx for casual lookups', with the cost trade-off of one extra LLM call.

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?

Goes far beyond the readOnly/openWorld/idempotent annotations by detailing safety short-circuits (low-confidence matches, closed/inactive markets), status values (low_confidence_match, market_closed_or_inactive), wide-spread tradeability flag, cancellation-rule parsing, fallback behavior on GDELT 429s, and notes on interpreting resolver confidence. No contradiction with annotations.

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

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

The description is long but front-loaded with a purpose sentence and organized by labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Every section adds non-redundant detail relevant to using the tool correctly. However, it could be tightened and formatted with bullets for readability; it's comprehensive rather than concise.

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

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

With no output schema, the description compensates by thoroughly documenting the response envelope (market, analysis, evidence, parent_event), resolver contract fields, acceptance states, and handling of edge cases (closed markets, wide spreads, cancellation rules). It also provides fan-out examples for multiple classifiers, making it complete for a tool of this complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description repeats the market input formats already in the schema and adds fan-out examples, but does not add new semantic detail for depth or include_raw beyond what the schema already states. It does not degrade, but also doesn't enhance parameter understanding.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from sibling tools by framing the use case: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'.

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

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

Provides explicit 'Use for' phrases that indicate when to invoke the tool. However, it does not explicitly name alternatives or state when not to use it (e.g., for cross-market edge scanning one might use polymarket_edges). This is clear context but lacks exclusions, so 4.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses important behaviors: false results mean invalid, name/address may be returned as '---' even for valid numbers, and service unavailability errors (MS_UNAVAILABLE, etc.) should be interpreted as 'could not check', not 'invalid'. This adds crucial context for interpreting results.

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

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

The description is three sentences with no wasted words. It front-loads the core purpose, then adds essential caveats about result interpretation and error handling. Every sentence contributes value.

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

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

The description covers the tool's purpose, return value semantics, edge cases (national service downtime), and data availability quirks. Given the simple two-parameter schema and no output schema, this is sufficient for an agent to use the tool correctly.

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

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

The input schema already provides comprehensive descriptions of both parameters, including examples, prefix-stripping behavior, and the Greece 'EL' nuance, covering 100% of parameters. The description itself adds no additional parameter details, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: validating EU VAT numbers against VIES. It uses a specific verb ('Validate'), names the resource ('EU VAT number', 'VIES'), and distinguishes it from the listed sibling tools, none of which perform VAT validation.

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

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

The description provides clear usage context: it's for validating EU VAT numbers. While it doesn't explicitly name alternatives or exclusions, the tool's unique purpose among siblings makes the use case self-evident. It also specifies the input format expectations indirectly through the schema.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds crucial context: it pulls from SEC EDGAR/XBRL, handles off-calendar fiscal years, sorts by primary metric, and returns paired data with citation URIs. It also quantifies the benefit ('Replaces 8–15 sequential lookups'). No contradiction with annotations.

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

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

The description is front-loaded with trigger phrase examples, then follows with purpose, data details, and behavioral notes. Every sentence earns its place—no filler, no repetition of schema fields. It is dense but structured to be scannable.

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

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

Given the tool has no output schema, the description compensates by stating what is returned ('paired data + pipeworx:// citation URIs per entity'). It covers both entity types, the 2–5 count constraint, sorting behavior, and the data sources. This is complete for an agent to invoke correctly without additional lookups.

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 type and values. The description adds meaning beyond the schema by clarifying the data sources per type (e.g., '10-K revenue + net income + cash + long-term debt' for company, 'FAERS adverse-event counts' for drug), providing examples, and explaining sorting behavior. This is substantial added value over the schema.

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

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

The description clearly states a specific verb and resource: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It also lists trigger phrases ('which is bigger', 'rank these companies') that distinguish it from sibling tools like entity_profile (single-entity lookup) and search tools. The distinction from sequential lookups is explicit.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing direct guidance on when to use this tool versus alternatives. It also enumerates concrete phrasings that trigger this tool, making the decision boundary 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?

Discloses significant behavior beyond annotations: account/paid-tier requirements, that it is NOT open-web search, explicit gaps[] never invented, fetchable citations, semantic excerpting, latency expectations, and contradiction detection. No contradictions with readOnly/idempotent/destructive hints.

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

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

Long but front-loaded with the account warning and highly structured (what it does, alternatives, depth modes, return packet, latency). Some redundancy ('NOT open-web search' appears twice) and the second-hop paragraph is dense, but every sentence adds value.

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

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

With no output schema, the description fully covers the return format: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[]. Also explains latency, depth options, and second-hop recovery, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: explains each depth's hop behavior and cost implications ('depth:"thorough" needs a paid plan'), and clarifies that the question can be broad/multi-part with examples.

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

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

The description clearly states the tool's core function: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' with decomposition into facets and parallel routing. It distinguishes from siblings by explicitly naming ask_pipeworx as the alternative for single lookups and current-news queries.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', plus concrete exclusions: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. Also notes account prerequisites and when to fall back to ask_pipeworx if not signed in.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral detail about the return payload (top-N tools with names, descriptions, full schemas, and curated examples) and that results are immediately callable without a second lookup. It does not cover potential latency or rate limits, but that is not necessary given 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?

Three sentences, heavily front-loaded with purpose, usage, and return-value information. No fluff, every sentence carries essential information. The structure is easy to scan and understand.

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

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

The description fully covers the tool's role, when to use it, what it returns, and how to use the results. No output schema exists, but the description explains the output format clearly. Given the large sibling context, this description provides enough to let an agent decide to invoke it correctly.

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

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

Schema description coverage is 100%, with all 6 parameters fully documented in the input schema. The description reinforces that the query is a natural language description and mentions the limit's max value, but it does not add significant semantic meaning beyond what the schema already provides. This matches 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 opens with 'Find tools by describing the data or task' which is a specific verb+resource statement that clearly distinguishes this meta-tool from the many sibling tools. It also lists the domains it covers, making its scope unmistakable.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' This provides clear when-to-use guidance and implicitly differentiates from directly using a known 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 cover readOnly and idempotent behavior. The description adds extra behavioral context: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), discloses the USPTO PatentsView API sunset with soft-fail behavior, and describes the GDELT→GNews fallback. This goes well beyond what annotations express.

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

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

Although long, the description is dense and front-loaded: it starts with sample queries, then states the core function, gives explicit usage preference, enumerates return fields, and ends with input constraints. Every sentence carries useful content; there is no filler or redundancy.

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

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

For a complex multi-source tool with no output schema, the description thoroughly enumerates all return components (cik, recent_filings, fundamentals, patents, news, LEI) with specific details like 'up to 5' filings, 'LATEST 10-K Revenues + NetIncomeLoss + Cash', and the patents soft-fail. It also covers input constraints and the resolver fallback, making it complete for the tool's complexity.

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

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

The input schema has 100% description coverage for both parameters, including ticker/CIK format and the resolver hint. The description repeats these examples and reinforces the 'names not supported' rule, but adds no new syntax, constraints, or additional parameter meaning beyond the schema.

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

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

The description opens with concrete user phrases and states a specific verb+resource: 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes itself from chaining single-pack lookups and from resolve_entity, so sibling differentiation is strong.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also names an alternative for name-only inputs: 'names not supported (use resolve_entity first if you only have a name).'

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, so the description's core delete action adds little beyond the schema. The description adds context about clearing stale or sensitive data, which is useful but not a behavioral trait 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?

Two sentences, front-loaded with the action and resource. The second sentence provides practical usage guidance and sibling tool references without any fluff. 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?

For a simple one-parameter delete tool with good annotations, the description covers purpose, usage, and relationships. It does not describe return values or error behavior, but the simplicity and idempotentHint mitigate this gap. Sibling context reinforces its role.

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

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

Schema coverage is 100% (one required parameter 'key' with description). The description mentions 'by key' but does not add new meaning beyond the schema, so baseline 3 is appropriate.

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

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

Purpose is explicit: 'Delete a previously stored memory by key.' The verb 'Delete' and resource 'memory' are specific, and the key-based scope is clear. It distinguishes from siblings like 'remember' and 'recall' by explicitly pairing with 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?

Provides clear when-to-use guidance: 'context is stale, the task is done, or you want to clear sensitive data.' However, it does not state when not to use or explicitly name alternatives, only complementary 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?

The description discloses the tool's behavior: it fetches the page, extracts key metadata, and outputs a text blob, which goes beyond the readOnly/idempotent annotations by revealing external network activity. It does not mention failure modes or rate limits, but it is consistent 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 concise and front-loaded, with the primary action in the first sentence and supporting details in a structured list. Every sentence contributes useful information.

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

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

Without an output schema, the description appropriately clarifies the return value ('single text blob ready to drop at site-root/llms.txt') and the markdown format. It does not cover edge cases, but the annotation set is strong and the tool is simple.

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 both parameters (url and max_links) with 100% coverage. The description does not add additional parameter-level guidance, so the baseline of 3 applies.

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

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

The description clearly states the tool's function: generating a production-ready llms.txt file from a URL, including the process of fetching and extracting content. It does not explicitly distinguish from sibling tools like scan_competitor_ai_presence, but the specific output (llms.txt) is unique enough.

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 three concrete use cases (client indexing, personal project, competitor audit) that indicate when to use the tool. It lacks explicit exclusions or alternative tool references, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds the 'caller's' scope (only own subscriptions) and the specific return fields, plus the distinction between active and inactive (related to include_inactive).

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: purpose, return fields, and usage guidance. Front-loaded and 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?

For a simple list tool with full annotations and one documented parameter, the description sufficiently covers what the tool does, its scope, return fields, and when to use it. 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 coverage is 100%, with include_inactive fully described. The description mentions 'active subscriptions' which aligns with the parameter but doesn't add semantics beyond the schema.

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

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

The description explicitly states 'List the caller's active subscriptions,' which is a specific verb+resource. It also lists the return fields, distinguishing it from subscribe/unsubscribe siblings.

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

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

It provides explicit use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel,' which clearly references when to use this tool in relation to adding or cancelling subscriptions.

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

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

With all annotations false, the description takes on full behavioral disclosure. It explains the async claim_token flow, rate limit ('5 per identifier per day'), that it's free, and how feedback affects roadmap. 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 longer than average, but each sentence contributes operational value: usage contexts, exclusions, token mechanics, rate limits, and quota impact. It front-loads the main purpose and remains well-structured, though a few sentences could be tightened without losing meaning.

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

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

Despite no output schema, the description fully explains the tool's behavior, return values (claim_token, later status), and lifecycle. It covers prerequisites, limitations, and workflow, making it complete for a feedback tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful guidance for the claim_token parameter (pass it back later with no other arguments to read the reply) and for message content (don't paste end-user's prompt, be specific). This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb and resource, and distinguishes itself from sibling tools by framing this as feedback for Pipeworx's own tool catalog, not for other MCP servers.

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

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

The description gives explicit when-to-use scenarios (bug, feature/data_gap, praise) and an explicit exclusion: 'if the tool came from a different MCP server... file it with that server instead.' It also clarifies that Pipeworx tool names are those listed by this connection, providing a clear decision rule for the agent.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds valuable context: derived from CF analytics-engine, no PII, cached 5min-1h depending on window. This explains data origin and caching behavior beyond the annotations.

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

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

The description is concise yet comprehensive: three sentences front-loaded with the core purpose, followed by numbered use cases and final caveats. Every sentence adds value and the structure is easy to scan.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers what it returns, data source, privacy, and caching. It is sufficient for an agent to invoke the tool correctly without further ambiguity.

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

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

Schema coverage is 100% with a clear description for the window parameter including enum values and semantics. The description repeats the window options but adds no new parameter information. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a recent window, with specific use cases. It distinguishes itself from siblings like discover_tools by focusing on aggregate agent behavior rather than available tools.

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

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

It lists three explicit use cases (discovering hot data sources, confirming canonical tool choice, aligning use case with agent needs). This provides clear context but does not explicitly state when not to use the tool or name alternatives, so no exclusions are given.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint). It discloses specifics like the fill check against live CLOB depth, the meaning of realizable_edge_pp <= 0 (do not trade), the semantic anchor Jaccard threshold, and the partition filter for placeholder slugs. This provides deep behavioral context with no contradictions.

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

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

The description is longer than typical but front-loaded with a clear overview and organized by mode. Each section (trending_scan, event, topic, semantic anchor, partition filter, fill check) earns its place, though the all-caps section headers and extensive detail make it slightly verbose. A 4 balances thoroughness with conciseness.

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 lack of an output schema, the description fully covers return values (opportunities[], partition_check, fill_check fields), edge cases (thin_legs, placeholder filtering), and practical usage (when realizable_edge_pp <= 0). It leaves no significant gap for an agent to select and invoke it correctly.

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

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

While the schema already covers both parameters (100% coverage), the description adds substantial semantics: event slugs and full URLs accepted, topic seed question examples, and the behavioral differences between modes. It also explains that omitting args triggers trending_scan, which is not in the schema. This significantly enriches 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 finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes itself from siblings by detailing three modes (trending_scan, event, topic) and even points to polymarket_fill_risk for custom sizing, making its purpose and scope 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?

Explicit usage guidance is provided: call with no args for trending_scan, pass 'event' for a specific market, or 'topic' for cross-event scanning. It also offers conditional recommendations ('event' recommended for a specific market) and names alternatives ('For custom sizing use polymarket_fill_risk'), clearly defining when to use this tool versus others.

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

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

Beyond the annotations (readOnlyHint=true, etc.), the description discloses many behavioral traits: 1-hour KV cache, placeholder-slug filtering, partition skipping >20% placeholder, funnel diagnostics, and the 24h-move warning. This significantly enriches the agent's understanding of side effects and edge cases.

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

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

The description is a dense wall of text. While the first sentence clearly states purpose, the remainder is an exhaustive data dump with ALL CAPS, parentheses, and nested lists. It is not concise, making it harder for an agent to quickly extract the most relevant information. It would benefit from structured sections, but the content is valuable.

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

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

Given the tool's complexity (three segments, multiple knobs, diagnostics) and no output schema, the description is exceptionally complete. It explains the response top-level (by_segment, fed_candidates, _diagnostics), what each opportunity carries (edge_pp_net, kelly_fraction, liquidity), and why segments might be empty (funnel counters, filter_skips).

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, but the tool description adds crucial cross-parameter context, such as how min_liquidity/max_spread_pp act as tradeable-edge filters and specifically how min_partition_leg_kelly applies to per-leg Kelly (since parent-level kelly is always 0 for partitions). This goes beyond the schema.

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

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

The description states a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also gives an explicit use case ('what should I bet on today') and details unique segmentation (model families) that differentiates it from sibling tools like polymarket_arbitrage.

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

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

The description provides a clear context for when to use the tool ('agents discover opportunities without paging hundreds of markets') and includes caveats (e.g., Fed bets excluded, rare-by-design). However, it does not explicitly name alternatives or exclusion conditions, 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?

The description goes far beyond the annotations by explaining detailed behavioral traits: the 60-day snapshot TTL, cache-miss gaps in snapshot_dates, decay computed on daily closes net of slippage, and the meaning of trend and expired fields. This rich context is not present in the readOnly/idempotent hints and is essential for correct interpretation.

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

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

The description is lengthy but well-structured into sections (Args, RESPONSE, LIMITS) and front-loaded with a clear purpose. Every sentence carries essential information, and the use of formatting improves readability. While it could be slightly trimmed, its length is justified by the complexity of the tool.

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

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

The description fully specifies the response structure (tracked[], expired[], snapshot_dates[]) with field semantics, along with data caveats and limitations. Since there is no output schema, the description carries the full burden of explaining return values, and it does so thoroughly.

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

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

The schema already documents both parameters with descriptions and defaults. The description adds semantic value by explaining that days is a lookback bounded by the 60-day TTL and window selects a snapshot family (24hr|1wk|1mo). It also clarifies how these parameters affect the returned time-series, which is beyond the schema's information.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?'), and the mention of distinguishing fresh vs old edges differentiates it from siblings like polymarket_edges.

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

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

The description provides clear context for when to use the tool: when assessing edge persistence and decay over time. It contrasts fresh and old edges, implying this is for temporal analysis rather than current edge discovery. However, it doesn't explicitly name alternatives or state when not to use it, so it stops short of the highest score.

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 readOnly, idempotent, and non-destructive, which the description complements rather than repeats. The description discloses rich behavioral detail: it 'walks the ladder,' returns specific fields like top_of_book and vwap_fill_price, interprets size_usd differently for buys vs sells and basket notional, and explicitly warns about partial-fill directional risk. No contradiction with annotations.

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

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

The description is dense but exceptionally well-structured, with explicit CAPS section markers (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) and a front-loaded purpose. Every sentence provides either a constraint, a return field, or rationale, and no content is redundant or filler. It earns its length by covering a complex tool with two modes in a scannable format.

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 to lean on, the description fully enumerates return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, verdict, thin_legs[], max_clean_notional_usd, forced_directional_risk), explains size_usd semantics, and highlights the key risk scenario (partial fills turning an arb into directional exposure). This is complete for an advisor/check tool, giving the agent all necessary context to invoke and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by stating the exclusivity constraint ('REQUIRES one of market or event') and clarifying mode-dependent behavior for size_usd (max spend vs target proceeds vs settlement notional). It also explains default behavior for basket side auto-selection, which enriches 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 opens with a specific, informative purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes between single-market and basket modes, lists return attributes, and explicitly ties usage to sibling tools ('USE THIS before acting on any polymarket_arbitrage... or any polymarket_edges trade above ~$500'), making it unmistakable what the tool does and how it differs from similar 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 the tool ('USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500') and explains why ('theoretical overround on thin books is not capturable, and partial basket fills convert an arb into an unhedged directional position'). It also provides mode-specific input requirements and a warning about the dominant loss mode, offering strong guidance beyond mere existence.

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

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

The description goes far beyond the annotations by detailing compatibility_warning trigger conditions (matched_pairs:0 semantics), temporal_alignment behavior, and the skipped_cross_type/subtype counters. It openly warns that spreads may be meaningless across temporal gaps or non-equivalent bet shapes, which is critical behavioral context not available from the read-only/idempotent hints.

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

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

The description is long but well-structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS) and dense, purposeful sentences. It could be trimmed slightly, but each section earns its place given the tool's complexity.

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

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

With no output schema and a complex response structure, the description thoroughly documents response fields, safety warnings, temporal alignment, and skip counters. It also sets realistic expectations about the rarity of tradeable spreads, making it complete for an agent to invoke and interpret correctly.

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

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

Schema coverage is 100%, but the description adds significant meaning by explaining the semantic split between the `topic` macro list and the explicit `kalshi_event_ticker`/`polymarket_event_slug` overrides. It clarifies that explicit parameters override topic-mapped sides and provides concrete examples, which exceeds the schema's per-parameter descriptions.

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

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

The description clearly identifies the tool as a cross-venue spread calculator between Kalshi and Polymarket for matching resolving questions, with a specific verb ('Cross-venue spread') and resource. It distinguishes itself from siblings like polymarket_arbitrage by emphasizing the Kalshi–Polymarket pairing and the safety warnings about non-equivalent bet shapes.

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 describes TWO MODES with concrete examples: the `topic` shortcuts and explicit ticker/slug pairings, and states when each is appropriate. It also provides strong when-not guidance by explaining that pre-mapped topics often return compatibility_warning and that 'pre-mapped ≠ tradeable', plus how to interpret warnings.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable context: scoping to identifier (anonymous IP, BYO key hash, account ID) and the ability to list all keys when omitted. It does not detail return format or error behavior, but for a read-only tool with good annotation coverage, this is sufficient.

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

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

Three sentences, front-loaded with the primary action, then usage context, then tool pairing. Every sentence earns its place with no redundancy or fluff.

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

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

The tool is simple (one optional parameter), schema covers it fully, and annotations are strong. The description explains purpose, usage, scoping, and alternatives. It does not describe the output/return structure, which could be relevant for a recall tool, but given the simplicity and existing structure, the description is nearly complete.

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

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

Schema description coverage is 100%, so the schema already fully describes the 'key' parameter. The description reinforces this by explaining the 'omit to list all keys' behavior, which is also in the schema. It adds no new parameter-level detail beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description uses specific verbs ('Retrieve', 'list') and identifies the resource ('value previously saved via remember', 'all saved keys'). It clearly distinguishes this tool from sibling tools 'remember' and 'forget' by explaining the retrieval/list 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 explicitly states when to use the tool ('Use to look up context the agent stored earlier') and provides examples of use cases. It also names alternatives ('Pair with remember to save, forget to delete'), giving clear guidance on tool selection.

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

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

Annotations declare readOnlyHint=true, but the description introduces mark_read:true, which flags events as read and mutates state. This contradicts the read-only annotation, so the description is misleading about the tool's side effects. Annotation contradiction flagged.

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

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

Three sentences with no fluff. The primary action is front-loaded, followed by return contents, filtering methods, mark_read behavior, and an alternative access method. Every sentence carries meaningful information.

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

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

Covers return contents, filtering, mark_read effect, polling suitability, and an alternative REST endpoint. With no output schema, it sufficiently describes what the caller gets, though it does not explicitly state that results are returned as a list or mention pagination.

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 all 5 parameters. The description adds value beyond the schema by giving a concrete type example (sec_8k), clarifying since as ISO timestamp, and explaining that mark_read affects future calls by only returning newer events.

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 pulls fired events from the subscription feed, with specific details about return contents (source, citation_uri, raw payload). It distinguishes itself from sibling tools by focusing on alerts and the evaluator-persisted feed.

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 usage context by noting polling works fine and offering an alternative HTTP endpoint for scripts/dashboards. Does not explicitly name sibling alternatives but implies when the tool is appropriate.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses important behavioral traits: parallel fan-out to multiple sources, GDELT→GNews fallback on rate limits/5xx, and the PatentsView API sunset causing a soft-fail until reactivation. This is valuable context not captured by 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 a single dense paragraph but front-loads the core purpose and then logically covers sources, parameters, return format, and alternatives. Every sentence adds operational value, though the density could be improved with bullet points for readability. It is appropriately sized for the tool's complexity.

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

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

Given no output schema, the description compensates by specifying the return shape (changes[] grouped by source, total_changes count, pipeworx:// citation URIs). It covers all parameters, data sources, failure modes, and sibling differentiation. The description is fully self-sufficient for an agent to invoke the tool correctly.

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

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

Schema coverage is 100% for all 3 parameters, but the description adds semantic depth beyond the schema: it explains the `since` parameter accepts ISO dates or relative shorthand with concrete examples ('7d', '3m'), and clarifies that `value` can be a ticker or zero-padded CIK. This goes beyond the bare schema descriptions, though some redundancy exists with 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: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It lists specific data sources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly differentiates itself from entity_profile, making its purpose unambiguous and distinct from sibling tools.

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

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

The description provides explicit usage guidance: it maps natural-language queries ('what's new with X') to the tool, and gives an explicit alternative ('Use entity_profile instead when you want the static profile'). It also clarifies fallback behavior and encoding limitations, leaving no ambiguity about when to choose 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 indicate the tool is non-read-only, non-destructive, and idempotent. The description adds valuable behavioral context: scoping by identifier, persistence differences between authenticated users (persistent) and anonymous sessions (24 hours), and the key-value store structure. This goes beyond the annotations without contradicting them.

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

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

The description is concise and well-structured, front-loading the core purpose in the first sentence. It includes only relevant usage details, persistence behavior, and related tools, with no redundant or filler content. Every sentence contributes meaningfully.

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

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

For a simple tool with two string parameters and no output schema, the description thoroughly covers purpose, usage scenarios, scoping, persistence, and relationship to the memory tool family. It provides sufficient context for the agent to select and invoke the tool correctly without needing external documentation.

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

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

The input schema already provides 100% coverage for both parameters with clear descriptions and examples. The tool description adds minimal extra semantic value, only repeating the key-value pair concept already evident from the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose with a specific verb ('Save data') and resource ('data the agent will need to reuse later'). It also distinguishes itself from sibling tools by explicitly naming recall and forget as complementary counterparts, making the role unambiguous.

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

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

The description provides explicit guidance on when to use the tool ('Use when you discover something worth carrying forward') with concrete examples. It also mentions the companion tools recall and forget, giving clear alternatives and context for when to use each.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses multi-source behavior (SEC EDGAR, GLEIF, OpenFIGI, RxNorm), graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), and the policy of explicitly listing unresolved identifiers. This is rich, actionable behavioral context that annotations do not provide.

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

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

The description is long but economically structured: examples first, then core statement, then supported types with semicolon-separated details. Every sentence contributes context, though the pipeworx citation example is a minor extra that could be trimmed. Overall, it's appropriately dense for a multi-source resolver.

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 behavior, and it does so thoroughly: identifier labeling with sources, explicit unresolved list, graceful degradation, and supported input variants. It even covers the internal cascade effect, making it clear what the agent should expect from a call.

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

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

Schema coverage is 100% and includes descriptions for both parameters. The description adds value by explaining what each type returns (CIK, LEI, FIGI for company; RxCUI, ingredient, brand for drug) and how the value parameter is interpreted (ticker, CIK, name vs brand/generic). This enriches the schema without contradicting it.

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

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

The description opens with concrete example queries ('What's the ticker for…', 'find the CIK for…') that establish the tool's purpose immediately, then states precisely: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' This distinguishes it from siblings like entity_profile or compare_entities by focusing on ID resolution.

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

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

Explicit instruction: 'Use FIRST whenever you have a name but need an ID.' This gives a clear when-to-use directive and implies preference over alternatives. It also indicates the tool replaces 2-3 manual lookups, providing practical context for when it's worth calling.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks results, and returns a specific structure (score, confidence, signal density). This goes beyond the structured annotations, though it doesn't disclose potential rate limits or multi-probe 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 three sentences long, front-loaded with the main purpose, and includes a practical example. Every sentence adds value, and there is no redundant repetition of schema information 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?

The tool is well-specified: schema covers all parameters, annotations cover safety/behavior, and the description explains the return format in the absence of an output schema. It lacks only minor details such as error handling or rate limits, but for a read-only comparison tool, the description is sufficiently complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics by explaining that the entities array should contain 'your brand + N competitors' and that the first entry is treated as the 'subject' for narrative. It also clarifies the optional context parameter's purpose, which enriches what the schema alone 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 clearly states the tool compares AI visibility across multiple entities side-by-side, using a specific verb ('Compare') and resource ('AI visibility'). It also distinguishes itself from sibling tools by explicitly mentioning it probes entities with ai_visibility_check, indicating it's a multi-entity wrapper.

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 for competitive AI-marketing audits and gives a concrete example question. It mentions the underlying tool (ai_visibility_check), implying when a single-entity check would suffice, but it does not explicitly say 'use this instead of X' or list when not to use it.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral disclosures beyond that: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed lists timeouts. It also reveals the composite nature of the call.

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

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

The description is dense but every sentence earns its place: purpose, usage, return structure, ecosystem scope, and failure handling. It is front-loaded and efficiently structured for a tool with this complexity.

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

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

With no output schema, the description must explain return values, and it does: summary block fields, per-advisory detail, links, and alternative versions. It also covers the composite behavior and failure tolerance, making it fully complete for an agent to invoke and interpret results.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minor extra meaning by clarifying the package is npm-only and implicitly binding version to the 'is_latest' and 'recent alternative versions' output fields. This is slightly above baseline.

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

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

The description clearly states the tool's purpose: a composite 'should I add this npm package' check that fans out across deps.dev and bundlephobia. It uses specific verbs and a resource, and is distinct from all the sibling tools listed, which focus on other domains.

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 provides usage triggers: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', which tells when not to use 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 indicate read-only, idempotent, and non-destructive behavior. The description adds significant behavioral detail: embedding model, cosine similarity, 500-character overlapping windows, 200K character cap with truncation flagging, and return of character offsets and scores. This goes well beyond the annotations and helps the agent predict output format 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?

Three sentences, each earning its place: the first defines the core function, the second explains when and why to use it, and the third provides technical parameters and limitations. The description is front-loaded with the main purpose and avoids fluff.

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

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

The tool has no output schema, so the description must explain return values; it does (passages with character offsets and similarity scores). It also covers edge cases (truncation), technical behavior (embeddings), and usage context, making the description self-sufficient for an agent to select and invoke the tool correctly.

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

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

The input schema has 100% coverage with detailed descriptions for text, limit, and query. The description does not add new parameter-level semantics; it reiterates the idea that text should be previously fetched content, which is more of a usage hint than a parameter definition. Since the schema already defines parameters clearly, a baseline of 3 is appropriate.

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

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

The description opens with 'Semantic search INSIDE a fetched record', a specific verb+resource statement that clearly distinguishes the tool from siblings like ask_pipeworx_grounded, which is mentioned as a complement rather than a substitute. The title and description align to convey exactly 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 states when to use the tool ('Use when the record is too big to cram into the prompt') and names a related tool, ask_pipeworx_grounded, as part of a recommended workflow. This gives concrete guidance on choosing this tool over alternatives.

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

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

With annotations covering readOnly, idempotent, and non-destructive hints, the description adds context about what the output contains (national statuses and overall VIES availability) and the purpose behind the tool. This adds value beyond the annotations.

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

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

The description is two sentences that front-load the core function and then provide usage context. Every word earns its place; no unnecessary elaboration.

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 no-parameter tool, the description fully explains what is listed and why it is useful, including the relationship to check_vat. The annotations handle safety, and the output is clearly defined in the description.

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

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

The tool has zero parameters, so the baseline is 4 per the rubric. The description doesn't need to explain parameters, and the empty schema already covers the 100% parameter definition.

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 uses the verb 'List' and specifies the exact resource: EU member states' VAT-checking service availability plus overall VIES status. It distinguishes itself from the sibling check_vat by stating it's for distinguishing outages from invalid VAT numbers.

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 identifies when to use this tool: before/after a failed check_vat to determine if an outage is causing the failure. This is clear usage context, though it doesn't explicitly state when NOT to use it or mention alternative tools beyond check_vat.

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

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

The description goes well beyond annotations by disclosing account requirements, per-channel behaviors (always-on feed, optional email/sms/webhook), SMS limits (10/day), phone verification, one-time webhook signing secret, and auto-disable after 10 failing webhook runs. 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 longer than average, but each sentence earns its place by covering auth, subscription types, examples, and delivery details. It is well-organized, front-loading the core purpose, and the density is justified for a tool with nested parameters and multiple delivery channels.

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, no output schema), the description is exceptionally complete: it covers return value, auth prerequisites, all supported types with examples, all delivery channels, constraints, and operational caveats. The agent has enough context to invoke correctly and handle edge cases.

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

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

Even though schema coverage is 100%, the description adds meaningful semantics: item code meaning ('items:["5.02"] = officer change'), concrete examples for each subscription type, delivery channel specifics (verified phone, HMAC signing, webhook URL restrictions), and rate limits. This is substantial added value beyond the schema's field descriptions.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It also uniquely differentiates itself from siblings like list_subscriptions, recent_alerts, and unsubscribe by focusing on creation and mentioning the returned subscription id.

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

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

It provides clear usage context, notably the OAuth account prerequisite ('anonymous + BYO cannot persist subscriptions') and delivery-channel alternatives ('pull via recent_alerts or GET registry.pipeworx.io/alerts.json'). It does not explicitly list sibling tools for alternative use, but the when-to-use context is strong.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations by detailing the return content (category-bucketed example questions with exact tool+argument shape) and how the topic parameter changes the response (focus vs. full spread). This gives the agent a strong model of expected behavior without contradicting annotations.

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

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

The description is longer than average but front-loaded with example user queries and structured with a clear progression: triggers, purpose, return type, parameter behavior, and usage guidance. Every sentence contributes useful information, though a slight tightening could improve scannability.

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

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

Despite having no output schema, the description fully specifies the return structure and the optional parameter behavior. It also positions the tool within its sibling ecosystem by explicitly naming related meta-tools, making it a complete onboarding resource for an agent unfamiliar with Pipeworx.

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

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

The schema already provides full coverage for the 'topic' parameter with an enumerated list of focus areas. The description adds examples ('finance', 'pharma', 'betting') and clarifies that omitting the parameter yields a cross-category spread, reinforcing the parameter's meaning and optionality 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 the tool's purpose: to suggest example questions for Pipeworx, acting as an onboarding entry point. It enumerates various natural-language triggers ('What can I ask Pipeworx?', 'what can you do?') and explicitly names the return type (category-bucketed example questions with tool+argument shape), distinguishing it from siblings like discover_tools and ask_pipeworx.

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

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

The description explicitly instructs to 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions it is a gateway to learning meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.). It also clarifies when to omit or pass the topic parameter, providing clear usage context with no ambiguity.

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

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

Annotations indicate a non-readonly, non-destructive mutation. The description adds valuable detail that the operation deactivates rather than deletes, preserving historical events via recent_alerts, and enforces ownership. This goes beyond the structured annotations and helps the agent understand side effects.

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

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

Two sentences front-load the action and then provide two key constraints. 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 action, ownership, deactivation semantics, and data availability. It omits return values, but there is no output schema and idempotency is hinted via annotations, so this is adequate for a simple mutation with one parameter.

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

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

The schema already fully describes the single 'id' parameter (100% coverage). The description adds only generic 'by id' wording, so no meaningful new parameter semantics are provided.

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 ('Cancel') and resource ('subscription by id'), clearly distinguishing it from sibling tools like subscribe and list_subscriptions. The ownership note adds further specificity.

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

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

The description gives clear context: you can only cancel your own subscriptions, and the row is deactivated rather than deleted, which affects future behavior. It does not explicitly mention alternatives (e.g., use subscribe to create), but the context is sufficient for typical 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 provide readOnly/openWorld/idempotent/non-destructive hints, but the description adds extensive behavioral context: the full verdict set (confirmed, approximately_correct, refuted, inconclusive, unsupported, could_not_verify), the distinction between could_not_verify (check did not happen, carries verification_error) and unsupported (no source found), and the pipeline behavior with verbatim evidence and citation. This far exceeds the structured fields and gives the agent critical interpretation rules.

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 systematically structured: trigger phrases, usage rule, routing logic, return contract, caller warnings, and efficiency rationale. It front-loads the most recognizable user intents and keeps warnings together at the end. Some phrasing is slightly repetitive, but the complexity of the tool justifies the length.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: verdict list, grounded/structured actual value with citation, reasoning, and error semantics for verification_error. It also explains the two pipeline paths and the meaning of 'unsupported.' This is complete enough for an agent to invoke the tool and interpret results correctly.

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

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

The input schema already documents both parameters with 100% coverage, but the description adds important semantic nuance: tolerance_pct overrides the tolerance implied by the claim wording, suggests values 1–2 for hallucination detection, and notes the default cap at 5. It also gives concrete example claim formats for the 'claim' parameter, supplementing the schema without redundancy.

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

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

The description opens with common user phrasings ('Is it true that…', 'fact check', 'verify the claim that…') and then states the core verb: natural-language claim verification against authoritative sources. It clearly identifies the tool's resource (factual claims) and scope (company-financial via SEC EDGAR + XBRL fast path; all other claims via grounded pipeline), distinguishing it from general-purpose research or ask tools. While it does not explicitly name sibling tools, the domain and behavior are specific enough to differentiate it.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' giving a clear trigger condition. It also explains the routing behavior for company-financial vs. other claims and notes that it replaces 4–6 sequential calls, which informs when to choose this tool over a manual multi-step pipeline. It does not name sibling tools or state explicit exclusions, but the guidance is strong.

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