Geoboundaries

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

Annotations already indicate readOnly and idempotent, so safety is covered. The description adds valuable behavior beyond this: the default model is free, using Anthropic requires a BYO key with direct cost to the user, and the return structure is disclosed. No contradictions.

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

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

Three sentences, each earning its place: purpose, model/cost behavior, return format and use cases. Front-loaded with the primary action, no redundant filler.

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

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

For a simple 4-parameter tool with no output schema, the description covers the return value (per-model score/confidence/signals/raw_response + combined view), the optionality of models, cost implications, and concrete use cases. This is sufficient for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the default model behavior and that `_apiKey` is only needed for Anthropic and incurs direct costs. This helps correctly populate the parameters.

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

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

The description uses a specific verb+resource: 'Probe one or more LLMs for what they know... and score visibility (0-100) per model.' This clearly distinguishes it from sibling tools like ask_pipeworx or compare_entities by focusing on AI visibility scoring across multiple models.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model and how to enable Anthropic probing. It doesn't explicitly name alternative tools, but the context is clear enough for an agent to decide when 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds context about routing to 5,529 tools, returning structured answers with citation URIs, and being a fast single call, which enriches behavioral expectations without contradicting 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 dense but well-organized, front-loading the key instruction ('PREFER OVER WEB SEARCH') and following with domains, examples, and escalation paths. It is longer than average, but every sentence contributes, making it appropriately sized for a complex meta-tool.

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

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

For a tool with no output schema, the description explains the return format ('structured answer with stable pipeworx:// citation URIs'), covers supported domains, and clarifies when to use alternatives. Missing details like error handling or pagination are minor given the tool's breadth.

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

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

Schema coverage is 100% with clear alias descriptions. The description adds value by giving concrete example questions ('current US unemployment rate', 'Apple's latest 10-K') that illustrate what to put in the question parameter, but it doesn't redefine the schema semantics.

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 ('PREFER OVER WEB SEARCH') and resource ('questions about current or historical data'), clearly distinguishing it from siblings like ask_pipeworx_grounded and deep_research. It lists concrete domains and example questions, making its purpose unambiguous.

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

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

Gives explicit when-to-use criteria ('Use whenever the user asks...') and when-to-step-up alternatives ('Step up only when needed: ... use ask_pipeworx_grounded; ... use deep_research'). Also notes it works on every tier and is the default entry point.

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 beta status, live candidate routing experiments, current no-candidate state, and the comparative evaluation process. It also clarifies that it is a fully functional router with no fallback, adding substantial behavioral context.

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

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

The description is dense and well-structured, with each sentence providing critical information: beta status, identical scope, current candidate state, usage guidance, and fallback behavior. It is longer than average but every sentence earns its place without redundancy.

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

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

For a complex universal router with 5,529 tools, the description covers what it does, its relationship to ask_pipeworx, current experimental status, and usage implication. Since no output schema exists, the mention of 'same response shape' as ask_pipeworx adequately addresses return expectations. The context is complete for an agent to invoke it appropriately.

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

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

Schema coverage is 100% with all parameters being aliases for 'question', so the schema fully documents semantics. The description adds no additional parameter-specific detail, only referencing 'same arguments' as ask_pipeworx, which doesn't go beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a beta universal router with 5,529 tools, same arguments, and same response shape as ask_pipeworx. It distinguishes itself from the stable sibling by noting candidate routing improvements and current identical behavior, leaving no ambiguity about its 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 says to use it 'exactly like ask_pipeworx when you want the newest routing' and contrasts it with the stable router, giving clear when-to-use guidance. While it doesn't explicitly state when not to use it, the stable/experimental distinction implies that ask_pipeworx is for stability, making the guidance effective.

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

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

The description adds substantial behavioral context beyond annotations: it details the grounded extraction process, the exact success and refusal response structures, and the cost implication. It also clarifies that answers are derived only from tool results, preventing hallucination. 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 well-structured, leading with the core value proposition, then mechanics, output format, use cases, and cost tradeoff. Every sentence contributes useful information, though it is slightly long and could be broken up for readability.

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

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

Considering the tool's complexity and lack of an output schema, the description fully covers behavior, return types, refusal reasons, recommended usage, and relationship to siblings. It is complete for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100% with all parameters documented as aliases for the natural language question. The description does not add extra semantic detail beyond what the schema already provides, 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 identifies the tool as a 'Hallucination-resistant answer mode' and explains its routing and extraction behavior in detail. It distinguishes itself from the sibling 'ask_pipeworx' by emphasizing grounded extraction and explicit refusal handling.

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

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

Explicitly states when to use ('use whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), including a cost tradeoff. This provides clear guidance relative to alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, and the description adds substantial behavioral nuance: both low-confidence and closed-market paths are blocking, resolver contract with confidence levels and alternatives, parent-event extraction, news fallback fields, wide-spread warnings, and cancellation-rule risk. This gives agents critical safety and interpretation context far 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?

Although lengthy, the description is densely packed with useful information and structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT) that make it scannable. Every sentence adds operational value for a complex tool; 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?

With no output schema, the description fully documents response fields (result.market, result.analysis, result.evidence), the resolver contract, parent_event behavior, news fallback mechanics, and edge cases like wide-spread markets and cancellation-rule risk. It even explains the two blocking routes and advises when to check cancellation rules, making it robust for safe agent usage.

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

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

The schema has 100% parameter description coverage, and the description further enriches it: 'depth' is clarified with 'quick = 2-3 evidence sources' and default thorough, 'include_raw' explains the size tradeoff (under ~20KB vs 50KB-500KB) and intended use, and 'market' is given concrete slug/URL/question examples. The extra semantics directly inform invocation and response handling.

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

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

The description opens with a clear, specific verb-resource pairing: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It then details input forms (slug, URL, question text) and the pipeline (resolve, classify, fan out, return evidence packet plus comparison), effectively distinguishing it from general research or Polymarket edge 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 lists intended use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z', and provides extensive fan-out examples per bet category. However, it lacks an explicit 'when not to use' or named alternative tools, so while context is clear, it could go further in differentiation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive; the description adds substantial context beyond annotations: data sources (SEC EDGAR/XBRL, FAERS, FDA), specific financial metrics, off-calendar fiscal year handling, sorting by primary metric, and output format including citation URIs. No contradiction.

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

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

The description is lengthy but every sentence serves a purpose: query triggers, core purpose, preference rule, type-specific details, sorting behavior, and return format. It is front-loaded with examples but remains well-structured and information-dense for a tool with two modes and multiple data sources.

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

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

No output schema exists, yet the description explains return contents (paired data, citation URIs) and sorting behavior. It also covers data provenance and edge-case handling (off-calendar fiscal years), providing a complete picture for the agent to invoke the tool correctly without further probing.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description enriches this by explaining how 'type' determines data pulled (10-K metrics vs FAERS/FDA counts) and clarifying the 2–5 entity limit for 'values'. This adds meaningful context beyond the raw enum/array definitions, though the schema already covers basics.

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

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

The description clearly states this tool performs 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' and supports comparison/ranking queries like 'X vs Y' and 'which is bigger'. It distinguishes itself from single-entity alternatives by emphasizing it replaces 8–15 sequential lookups, aligning with sibling entities like entity_profile.

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

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

Explicitly instructs to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving clear when-to-use guidance. It also describes type-specific behavior (company vs drug) and output sorting, but does not explicitly name sibling alternatives or exclusion cases, leaving minor room for improvement.

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

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

Despite annotations (readOnly, openWorld, idempotent, non-destructive), the description adds substantial behavioral detail: parallel decomposition across 5,529 tools, output shape (verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[]), latency expectations, semantic excerpting, and the guarantee of never inventing answers. This far exceeds the annotation basics.

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

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

The description is long but densely informative, with each sentence serving a purpose (account warning, use-case examples, output format, latency, caveats). It is front-loaded with the critical account requirement. It could be slightly trimmed, but given the tool's complexity, it is appropriately sized.

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 thoroughly explains the return value (findings packet with citations, gaps[], contradictions[], hop field) and operational details like latency and excerpting behavior. It covers all essential aspects for an agent to select and invoke the tool correctly, including limitations (empty gaps for non-structural topics).

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

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

The schema already covers both parameters thoroughly (question description says broad/multi-part is fine; depth enum explains quick/standard/thorough semantics). The tool description adds marginal value like the paid plan for 'thorough' and second-hop iteration details, but these are mostly behavioral/contextual rather than parameter syntax, so the baseline 3 for high schema coverage 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 performs 'grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, explicitly distinguishing it from open-web search. It provides a specific verb+resource ('research across Pipeworx's structured data sources') and differentiates from sibling tools like ask_pipeworx by scope ('broad/multi-part questions').

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

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

It gives explicit when-to-use vs alternatives: 'For a single lookup use ask_pipeworx', 'prefer ask_pipeworx' for current news, and 'If you are not signed in, use ask_pipeworx instead'. It also specifies account/depth requirements, making the choice clear 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, idempotentHint=true, and destructiveHint=false, and the description adds important behavioral detail: it returns top-N relevant tools with names, descriptions, full input schemas, and curated examples, emphasizing results are ready to call directly with no second lookup. This is valuable context 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 but rich, with each sentence serving a purpose: definition, when-to-use, output details, and prioritization. The enumeration of domains is useful and not wasteful. It is well-structured and front-loaded with the core purpose.

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

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

Given the tool's complexity (6 parameters, aliases, no output schema), the description sufficiently covers return values, usage intent, and direct callability. The annotations handle safety, and the schema covers parameters. No critical context is missing.

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

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

Schema description coverage is 100%, so the schema and its property descriptions fully document the parameters and aliases. The description does not add parameter-level detail beyond the schema, which is acceptable given the high coverage, but it provides no extra semantics.

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: 'Find tools by describing the data or task.' It specifies the resource (available tools) and action (discover/browse/search), and differentiates itself from sibling tools by emphasizing discovery across many domains and providing ready-to-call schemas.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and instructs to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context and distinguishes it from directly using a specific 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, non-destructive behavior. The description adds substantial context: it fans out across multiple sources, returns specific fields (CIK, filings with URIs, latest 10-K fundamentals), notes the USPTO API sunset causing soft-fail, and describes a GDELT→GNews fallback. This goes well beyond the annotation metadata.

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

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

The description is dense and information-packed, with a clear front-loaded set of example queries. It could trim the redundant examples ("tell me about X" / "research Acme" / "brief me on Tesla") without losing meaning, but the overall structure of semicolon-separated output details and fallbacks is organized and purposeful.

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 accounts for return values, input constraints, limitations, and fallback behavior. It covers all major aspects an agent needs to invoke and interpret the tool, making it complete for its 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% and both parameters have descriptive docs. The description adds value with concrete examples ("AAPL", "0000320193") and reinforces the constraint that names are not supported, which is helpful but only slightly extends the schema.

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

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

The description states a clear, specific purpose: build a full cross-source profile of a US public company in one parallel call. It distinguishes itself from siblings by explicitly recommending use over chaining single-pack lookups and pointing to resolve_entity for name-only inputs.

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: when the user asks for a holistic view of a company, always prefer this tool over chaining SEC/XBRL/news lookups. It also states what inputs are supported (ticker/CIK) and that names are not supported, directing users to resolve_entity first.

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 destructiveHint and idempotentHint, and the description aligns by saying 'Delete'. It adds a subtle behavioral trait by noting 'previously stored memory', implying deletion applies only to existing keys. It also adds context about cleaning sensitive data. 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 two sentences, with the first sentence front-loading the primary action and the second adding usage guidance and complementary tools. Every sentence earns its place without unnecessary verbosity.

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

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

For a simple one-parameter tool with no output schema and no nested objects, the description is complete. It covers purpose, usage context, complementary tools, and the key parameter is fully documented in the schema. No significant gaps remain.

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

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

The input schema fully describes the single parameter 'key' with a description and example, so schema coverage is 100%. The description merely repeats 'by key' without adding new meaning beyond the schema, which meets the baseline for high schema coverage.

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

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

The description clearly states the tool deletes a previously stored memory by key, using the specific verb 'Delete' with the resource 'memory'. It distinguishes from siblings like 'remember' and 'recall' by positioning itself as the removal operation, and explicitly says 'Pair with remember and recall'.

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: 'Use when context is stale, the task is done, or you want to clear sensitive data'. It also names complementary tools ('remember and recall'), offering clear context for selection among siblings.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds valuable behavioral detail: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' and specifies the output is a 'single text blob ready to drop at site-root/llms.txt'. 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 three sentences with no redundancy. It leads with the core purpose, explains the mechanism, and concludes with practical use cases. 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 only two parameters and no output schema, the description fully covers the tool's behavior, output format ('Output is a single text blob ready to drop at site-root/llms.txt'), and use cases. Annotations cover safety. The description is complete for this simple tool.

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

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

The input schema has 100% coverage for both parameters, so the baseline is 3. The description adds context about what the tool does with the URL (fetches, extracts) but does not add new parameter-level details beyond what the schema already provides for max_links or url.

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: 'Generate a production-ready llms.txt file for any URL'. It uses a specific verb and resource, and distinguishes itself from siblings by focusing solely on llms.txt generation, which no other tool handles.

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

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

The description provides explicit use cases ('Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor') and clarifies the input is 'any URL'. However, it does not explicitly mention alternative tools or when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context by enumerating the exact metadata fields returned, listing download URL types, and noting the default product's CC-BY license—details 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 four sentences, each earning its place: purpose, ISO3 explanation, ADM level explanation, and product/license note. It is dense but not verbose, with clear front-loading of the core function.

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 thoroughly communicates the return payload (unit count, year, source, license, download URLs), fully explains all three parameters, and states defaults and licensing. It provides a complete picture of what the tool does and returns, leaving minimal 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 descriptions cover 100% of parameters, so the baseline is 3. The description adds value by providing concrete ISO3 examples, explaining ADM levels in a natural hierarchy, and clarifying the default product and license, enriching what the schema already provides.

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

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

The description opens with a specific verb and resource: 'Get administrative boundary metadata for a country from geoBoundaries'. It clarifies the return type (metadata with download URLs), distinguishing it from the sibling tool get_geometry which likely fetches geometry itself.

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

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

The description implies when to use the tool (when you need boundary metadata) and explains parameter semantics, but it does not explicitly mention alternatives or when not to use it. With get_geometry as a close sibling, a direct comparison would strengthen this dimension.

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

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

Annotations declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds behavioral context beyond these: payloads can be several MB, the tool refuses payloads over ~4 MB, it returns only simplified geometry, and adm="ALL" is invalid. This enriches the annotation info without contradiction.

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

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

The description is slightly long but every sentence adds critical information: what it fetches, size warning, size limit, alternative tool, and validity constraint. It is front-loaded with the main purpose and uses compact phrasing, though the warning could be considered a bit verbose for the score of 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 complexity (large payloads, restriction on adm='ALL', relationship to get_boundaries), the description covers the return type, size behavior, refusal threshold, and usage context. No output schema exists, but the description sufficiently explains what is returned and the 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?

Schema description coverage is 100%, so baseline is 3. The description does not add significant parameter-specific meaning beyond the schema; it focuses on response size and alternatives. It confirms product defaults indirectly via schema, but no extra semantic value is provided for the parameters themselves.

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 fetches simplified GeoJSON FeatureCollection geometry for a country/ADM level, using a specific verb and resource. It distinguishes itself from sibling get_boundaries by noting this tool only returns simplified geometry and explicitly recommends get_boundaries for other cases.

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

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

Explicit guidance is provided: 'Prefer get_boundaries unless you explicitly need the coordinates' and 'Not valid for adm="ALL"'. It also warns about payload size and directs users to get_boundaries for large payloads, covering both when-to-use and when-not-to-use.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds useful context beyond annotations by specifying the returned fields (id, type, params, created_at, last_fired_at, fire_count) and the default behavior of only including active subscriptions. It does not contradict any annotation.

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

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

The description consists of two tightly written sentences. The first states the action and output, the second explains when to use it. Every sentence earns its place, with no fluff or repetition.

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

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

For a simple list tool with one optional parameter and no output schema, the description is complete. It states what is listed, what fields are returned, and the intended usage contexts. The tool's simplicity and strong annotations mean no significant information is missing.

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

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

Schema coverage is 100% and the single parameter 'include_inactive' has a clear description. The tool description does not add any additional meaning beyond the schema; it simply restates the default behavior. This matches the baseline where 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 uses a specific verb and resource ('List the caller's active subscriptions'), clearly identifying what the tool does. It also lists the return fields and distinguishes the tool from siblings like 'subscribe' and 'unsubscribe' by framing it as a review/cancel-id lookup tool.

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

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

The description gives clear context for when to use the tool: 'review what you're monitoring before adding more' and 'to find an id to cancel.' It implies alternative workflows (subscribe/unsubscribe) but does not explicitly state when not to use it or name alternatives. This is clear usage guidance but not a full when/when-not/alternatives breakdown.

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 set to false, the description carries the full burden of behavioral disclosure, and it succeeds. It discloses the claim_token flow (filing without an account returns a token that can be used later to check resolution), rate limiting ('Rate-limited to 5 per identifier per day'), quota impact ('doesn't count against your tool-call quota'), and operational details (team reads digests daily). It also advises not to paste end-user prompts, adding practical behavioral context. No annotation contradiction exists.

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

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

The description is longer than typical, but every sentence delivers useful information: purpose, use cases, exclusions, token flow, rate limits, and quota. It is front-loaded with the primary purpose and uses clear, direct language. Some redundancy exists (e.g., the 'only Pipeworx connection' point is restated), but the structure is logical and not bloated. It earns a 4 rather than 5 due to its density.

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 moderate complexity (4 optional params, nested object, no output schema), the description is remarkably complete. It covers the tool's domain, when to use/discard it, the full claim_token lifecycle, rate limits, and input formatting guidance. The absence of an output schema is mitigated by explaining the return behavior ('returns a claim_token') in the description. This is fully 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 provides 100% description coverage for all four parameters, so the baseline is 3. The description adds meaningful semantic value by explaining the claim_token usage workflow in context ('pass it back later as pipeworx_feedback({claim_token:...})'), which goes beyond the schema's static parameter description. It also ties the context object to specific Pipeworx tools/packs, but the schema already handles that well. This extra operational context justifies a 4.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly distinguishes this tool from sibling ask/research tools by limiting it to feedback about Pipeworx connection tools, and it enumerates the types of feedback (bug, feature/data_gap, praise). This leaves no ambiguity about the tool's role.

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion rule: 'ONLY for tools served by this Pipeworx connection' and instructs to report other MCP servers' tools elsewhere. This is exemplary usage guidance with alternatives and exclusions.

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

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

Annotations already declare safe read-only and idempotent behavior; the description adds valuable context with data provenance (CF analytics-engine), a privacy guarantee (no PII), and a caching window (5min-1h). No contradictions with annotations.

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

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

Three tightly-scoped sentences: purpose, use cases, and data/caching details. No filler; the use-case list earns its length by improving selectability.

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

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

For a single-parameter read-only tool without an output schema, the description covers what it returns, the data source, privacy, and caching. The return shape is hinted at ('(pack, tool, count)'), which suffices for a simple tool.

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

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

The schema covers the only parameter (window) with an enum and meaning (24h/7d/30d). The description mentions the window options but adds no new semantics beyond what the schema already provides, so the baseline 3 applies.

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

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

The description opens with a concrete question ('What other AI agents are calling on Pipeworx right now') and specifies exactly what it returns (top tools, top packs, total call volume). It clearly distinguishes itself from sibling discovery tools by focusing on real-time aggregate usage from other agents, not generic tool discovery.

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

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

The description provides three explicit use cases that guide the agent on when to call this tool, such as discovering hot data sources or confirming canonical tool choice. It doesn't name alternatives or exclusions, but the use cases are actionable and sufficient for selection decisions.

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, revealing thresholds (deviation >3pp), placeholder filters (>20% -> null), fill-check pricing logic (realizable_edge_pp <= 0 means do not trade), and response structure. It provides rich behavioral context without contradicting the readOnly/idempotent annotations.

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

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

The description is long but well-organized with clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose. Every section contributes necessary operational detail for a complex tool, so the length is justified, though it could be tightened.

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

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

The description covers all critical aspects: modes, parameters, response shapes, similarity thresholds, placeholder filtering, and real-world fill-risk caveats. With no output schema, this text fully compensates by describing the response structure and edge cases, making the tool's behavior completely understandable.

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

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

Although the schema describes both parameters, the description adds significant value: example slug formats, accepted full URLs, how the topic is used to search related events, and the consequences of passing each parameter. This is precisely the contextual enrichment needed beyond the raw schema names.

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 via monotonicity violations and partition-sum checks. It distinguishes three modes (trending_scan with no args, event-mode, topic-mode) and references the sibling tool polymarket_fill_risk, making it distinct from alternatives.

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 guidance on when to use each mode: no args for trending scan, 'event' (recommended for a specific market), and 'topic' for cross-event scanning. It also explicitly directs to use polymarket_fill_risk for custom sizing, offering a clear alternative.

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

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

Annotations already declare the tool read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral detail: caching for 1 hour keyed on all knobs, diagnostics for empty segments (filter_skips, funnel counters), a 24h-move warning, and the Fed-exclusion caveat. This goes well beyond the static annotation flags and primes the agent for expected behavior.

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

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

The description is front-loaded with purpose but quickly becomes an exhaustive specification of model internals (per-sport α values, GDELT ratios, FRED log-returns, gate thresholds). While this information is useful, it makes the description overly long and hard to scan. A more structured or summarized format would improve conciseness without losing critical meaning.

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

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

With no output schema, the description carries the full burden of explaining the response, and it does so thoroughly: it details top-level segments (by_segment, fed_candidates, _diagnostics) and per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, market.spread_pp, market.volume). It also explains why segments may be empty and how knobs affect the returned opportunities, making the tool self-contained.

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

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

Schema coverage is 100%, providing a baseline of 3, but the description significantly enriches parameter understanding. For example, it explains that min_partition_leg_kelly applies to per-leg Kelly because parent-level kelly_fraction_half is always 0 for partition overrounds, and that max_spread_pp/min_liquidity serve as tradeable-edge filters. It also ties slippage_pp to Polymarket's zero-fee environment and typical bid/ask costs.

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

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

The opening sentence clearly states the tool's function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' and even provides a concrete use case ('what should I bet on today'). It differentiates itself from siblings by emphasizing the Pipeworx disagreement framework and the specific model-family segments it returns.

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

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

The description provides clear contextual guidance: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets' and offers detailed knob-based filtering instructions. However, it does not explicitly compare against sibling tools like polymarket_arbitrage or polymarket_edge_tracker, though the Fed-note section partially warns against relying on Fed-related signals in certain cases.

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

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

Beyond annotations (read-only, idempotent), the description explains data gaps (snapshots written on cache-miss), computation method (decay from daily closes of edge_pp_net, not intraday), signed values, and the meaning of expired opportunities. This is rich behavioral context that enables accurate 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?

Despite being long, every sentence earns its place: purpose, args, response structure, and limits are logically organized. Front-loaded with the core question, then structured sections. 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?

Without an output schema, the description fully documents return types (tracked[], expired[], snapshot_dates[]) with fields and semantic meaning. It also covers historical limits, data gaps, and computation basis, making it complete for a complex telemetry tool.

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

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

With 100% schema coverage, baseline is 3. The description adds meaningful context by labeling days as 'lookback' and window as 'snapshot family' and explicitly stating defaults and max, clarifying the role of each parameter in the overall snapshot architecture.

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's 'edge persistence and decay telemetry' built from snapshots, answering 'how long has this edge existed and is it shrinking?' This distinguishes it from siblings like polymarket_edges (current edges) and polymarket_arbitrage, with a specific verb and resource.

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

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

Provides explicit context on when to use it: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take)'. It doesn't explicitly list alternative tools, but the example makes the use case clear. LIMITS section adds practical constraints on applicability.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context beyond these: mode requirements, default sides, size interpretation differences (spend vs target proceeds vs settlement notional), return fields including verdicts, and critical risk disclosure about partial basket fills. It does not contradict annotations.

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

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

The description is long but information-dense, with every sentence adding necessary detail. It is structured by mode (SINGLE-MARKET vs BASKET) and uses clear delimiters (e.g., 'REQUIRES', 'USE THIS'). However, it is a single dense paragraph that could benefit from bullet points or section breaks to improve scanability, though no content is redundant.

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

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

Given no output schema, the description thoroughly covers return values for both modes: top_of_book, vwap_fill_price, slippage_pp, verdict, theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], and max_clean_notional_usd. It also covers edge cases (cannot_fill verdict, forced_directional_risk) and provides the 'why' behind usage, making it complete for a complex tool.

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

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

Schema description coverage is 100%, so baseline is 3, but the description enriches every parameter significantly. It explains the market/event mode distinction, the auto-detection logic for basket side, and the nuanced meaning of size_usd per mode (spend vs target proceeds vs settlement notional, with clamp range). This far exceeds the schema's terse 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, meaningful purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this tool from siblings by naming the arb-check use case and referencing polymarket_arbitrage and polymarket_edges explicitly. The verb 'check' plus resource 'live CLOB order-book depth' is specific and actionable.

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

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

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the two modes (single-market vs basket), when each is appropriate, and the rationale (theoretical overround on thin books is not capturable, partial basket fills lead to unhedged directional risk). This goes beyond generic context and names concrete alternatives.

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

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

The description goes far beyond the read-only, idempotent annotations by disclosing the compatibility_warning, temporal_alignment field, and skipped_cross_type/subtype counters as edge-case behaviors. It explains when spreads are mathematically meaningless, giving an agent critical 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?

Though dense, the description is structured with clear sections (modes, response, safety fields) and every sentence carries informational weight. It is front-loaded with the core purpose and then layers details, making it skimmable despite its length.

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

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

Given that there is no output schema, the description thoroughly covers response structure (leg-by-leg prices, top_spreads_pp), safety warnings, and failure modes. An agent is fully equipped to invoke the tool without guessing about return values or 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?

Schema coverage is 100% and each parameter is described in the schema, but the description adds semantic value by explaining the precedence of explicit tickers/slugs over topic-mapped sides and the override behavior. This enrichment beyond the schema justifies a score above the baseline of 3.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which clearly identifies the tool's purpose and distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges that focus on single-venue or different types of analysis. The scope is specific, and the two modes further clarify what the tool does.

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

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

The description provides detailed usage context, explaining the two modes and explicitly warning that most pre-mapped topics return compatibility_warning and that pre-mapped ≠ tradeable. It names alternatives or exclusions for sibling tools, but the warning about non-equivalent bet shapes effectively implies when not to use the tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it explains that results are 'scoped to your identifier (anonymous IP, BYO key hash, or account ID)', which is a meaningful behavioral trait not captured in the schema or annotations.

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

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

The description is two sentences, front-loaded with the primary action and mode, followed by usage context and scope. Every sentence conveys necessary information without waste, and the structure is easy to parse for an agent.

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

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

This is a simple tool with one optional parameter, no output schema, and rich annotations. The description covers purpose, modes, usage context, scope, and sibling relationships, which is fully sufficient for an agent to select and invoke the tool correctly. No critical information is missing.

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

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

The schema already provides 100% coverage for the single 'key' parameter, including the 'omit to list all keys' behavior. The description echoes this same semantic, adding illustrative examples but no new technical details. With high schema coverage, the baseline is 3, and the description does not exceed that baseline.

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

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

The description clearly states the tool's function with a specific verb ('Retrieve') and resource ('a value previously saved via remember'), plus a distinct secondary mode ('list all saved keys' when key omitted). It also explicitly distinguishes itself from sibling tools 'remember' and 'forget', making it 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 concrete use cases ('the user's target ticker, an address, prior research notes') and explains when to use the tool ('without re-deriving it from scratch'). It directly mentions the complementary sibling tools 'remember' and 'forget', effectively guiding the agent on when to use this tool versus alternatives.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints, so the description doesn't need to restate safety. It goes beyond annotations by disclosing the return structure (source, citation_uri, raw payload) and the stateful mark_read behavior that affects subsequent calls. This adds meaningful behavioral context not present in the schema or annotations.

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

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

The description is four sentences, front-loaded with the core purpose, and every sentence adds value: purpose, return payload, filtering options, stateful behavior, and alternative access. There is no redundancy or filler, making it efficient and easy to parse.

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

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

Given there is no output schema, the description compensates by describing the return payload fields and behavior. It also covers filtering, mark_read, and polling guidance, which are essential for an agent to use the tool effectively. It doesn't mention limit or unread_only, but those are fully documented in the input schema, so the description covers the remaining context adequately for a list tool.

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

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

Schema description coverage is 100%, so baseline applies. The description adds extra meaning by providing a concrete type example ('sec_8k'), clarifying the since parameter expects an ISO timestamp, and explaining how mark_read affects next calls. These details go beyond the schema's property descriptions and help agents use the parameters correctly.

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: 'Pull fired events from your subscription feed.' It clarifies the tool returns recent alerts from the evaluator's persisted feed, including source, citation_uri, and raw event payload. This clearly distinguishes it from sibling tools like list_subscriptions or recent_changes, which handle different resources.

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

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

It gives practical guidance: filtering by type/since, using mark_read to advance the read cursor, and note that 'Polls work fine' to indicate suitability for repeated calls. It also mentions the same feed is available via an HTTP endpoint for scripts/dashboards, providing an explicit alternative. It doesn't compare directly to sibling tools but offers clear context.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds substantial behavioral context: multi-source fan-out, GDELT→GNews fallback on rate-limit/5xx, USPTO soft-fail due to API sunset, and the exact return shape (changes[], total_changes, citation URIs). This goes well beyond the safety profile.

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

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

Though long, the description is densely packed with high-value information—examples, source details, fallback behavior, date formats, and output structure. There is no filler or tautology; every sentence earns its place and the structure is logical.

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 complex (three external sources, fallbacks, soft-fail) and has no output schema, but the description covers all major aspects: sources, window semantics, return structure, and the alternative entity_profile. An agent would know exactly what to expect and how to act.

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

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

The schema covers all parameters at 100%, so baseline is 3. The description adds extra value by explaining `since` relative shorthand formats, confirming `value` accepts ticker or CIK, and suggesting '30d' or '1m' for typical monitoring, which is helpful but not transformative.

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

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

The description explicitly states the tool is a change feed for companies over a time window, enumerating the data sources (SEC, GDELT/GNews, USPTO) and the output structure. It distinguishes itself from sibling entity_profile by contrasting dynamic changes vs static profile, making the purpose unambiguous.

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

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

The description gives clear example queries ('What's new with X', 'latest on Y') and explicitly recommends entity_profile for static profiles, providing an alternative. It also explains the fallback behavior between GDELT and GNews, so the agent knows when to use this tool and when not.

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 idempotent and non-destructive, and the description adds valuable context: persistent memory for authenticated users, 24-hour retention for anonymous sessions, and scoping by identifier. It does not contradict annotations, though it omits details about key overwrite behavior.

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

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

The description is front-loaded with the primary action and uses four tight sentences, each contributing useful information. There is no filler or redundant restatement of the tool's title.

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

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

For a simple two-parameter write tool with annotations and full schema coverage, the description covers purpose, usage context, persistence, scoping, and sibling relationships. It is fully sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% for both key and value parameters. The description adds concrete key examples and clarifies that value accepts any text, going beyond the schema's descriptions and reinforcing the key-value scoping context.

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 'Save data the agent will need to reuse later,' which specifies a clear verb and resource. It distinguishes the tool from siblings by naming recall and forget, and it provides concrete usage examples like ticker and address.

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 instructs when to use the tool: 'Use when you discover something worth carrying forward...' and gives examples. It also positions it against recall and forget, explaining pairing for retrieval and deletion, which makes the choice of tool obvious.

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

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

Even with read-only annotations, the description adds rich behavioral detail: it mentions cascading through multiple lookup endpoints, graceful degradation of LEI/FIGI enrichment when upstream services are unavailable, and explicit handling of unresolved identifiers via an 'unresolved' field. This exceeds what annotations alone provide and gives the agent a clear runtime model.

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

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

The description is long but well-structured: it front-loads with relatable user questions, then explains the core function, supported types, and key behavioral nuances. Each section earns its place, though the quoted examples could be tightened without losing meaning. It is appropriately sized for a tool with such breadth.

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

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

There is no output schema, so the description must compensate. It thoroughly explains input formats, output identifier types, sources (SEC EDGAR, GLEIF, OpenFIGI, RxNorm), fallback behavior, and the explicit reporting of unresolved identifiers. This is complete enough for an agent to understand what the tool will return and how it behaves.

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 has 100% parameter coverage, so the baseline is 3. The description adds value by giving concrete examples for each entity type (company accepts ticker, CIK, or name; drug accepts brand or generic) and explaining the source labeling behavior, which helps the agent construct valid inputs. This extra context justifies a 4.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical identifiers. It provides multiple examples of queries ('What's the ticker for…', 'find the CIK for…') and distinguishes itself from siblings by noting it is the first step when a name needs an ID. The verb 'resolve' and resource 'entity' are specific and unique.

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 instruction 'Use FIRST whenever you have a name but need an ID' is a clear when-to-use guideline. The description also lists supported types and input formats. However, it does not explicitly mention when NOT to use it or name alternative tools, so it misses the full when-not/alternatives aspect for a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds context that the tool internally calls ai_visibility_check for each entity, ranks by score, and returns confidence/signal density—useful behavioral insight beyond the annotations. No contradictions found.

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 action, and every sentence earns its place. It avoids redundancy with the schema and even includes a concrete example without becoming verbose.

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

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

Even without an output schema, the description explicitly states the return value (ranked list with score, confidence, signal density per entity), and covers the operational flow (probing, ranking, surfacing). It provides enough context for an agent to understand what to expect and when to invoke it, especially given the rich schema and annotations.

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

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

The input schema already provides 100% parameter coverage, so the baseline is 3. The description adds valuable semantic detail by stating the first entity in 'entities' is treated as the subject for narrative, which is not in the schema. It also clarifies that 'models' can be omitted for the default worker-ai, aligning with the schema's optional description.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, with a specific verb ('Compare') and resource ('AI visibility'). It also distinguishes itself from the sibling ai_visibility_check by emphasizing multi-entity comparison and ranking, and mentions the underlying probe mechanism.

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

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

Provides concrete use case ('competitive AI-marketing audits') with an example query, and implies it is the multi-entity counterpart to ai_visibility_check. However, it does not explicitly state when not to use the tool or name alternative tools for single-entity checks, leaving some room for interpretation.

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

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

Beyond the readOnly and idempotent annotations, the description discloses important operational behavior: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed will list timeouts while the rest still returns. This adds meaningful context about latency and failure modes that annotations alone do not convey. No contradiction with annotations.

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

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

The description is moderately long but each clause carries distinct information: composite nature, use cases, return fields, ecosystem scope, and failure behavior. It is well-structured with clear sequencing, though the final sentence is somewhat run-on. Slight over-elaboration but appropriate for the tool's complexity.

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

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

Given the tool's complexity and the absence of an output schema, the description compensates by listing the exact return fields, per-advisory details, links, and recent alternative versions. It also covers partial failures and latency, making the tool's behavior fully understandable for an agent. No significant gaps remain.

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

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

The input schema already provides 100% coverage with clear descriptions for both package and version parameters, including examples and defaults. The tool description does not add parameter-specific semantics beyond what the schema already states. Per the rubric, high schema coverage earns a baseline of 3, and there is no additional parameter explanation to raise 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 clearly specifies the tool as a composite npm package assessment, naming both data sources (deps.dev and bundlephobia) and the specific data points returned. It distinguishes itself from siblings by explicitly scoping to NPM and referencing direct deps.dev usage for other ecosystems. The verb "scan" plus the resource "dependency" and the detailed explanation make the purpose unambiguous.

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

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

The description explicitly states when to use: whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me". It also provides an explicit alternative for non-NPM ecosystems (use deps.dev:version directly), making the boundary clear. This goes beyond implied use and gives concrete triggers and exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds substantial behavioral details beyond that: it reveals the embedding model ('BGE-base-en embeddings + cosine over 500-char overlapping windows'), the character cap ('200K chars'), and the truncation behavior ('longer inputs are truncated and flagged'). It also clarifies the output structure (offsets and similarity scores), providing a transparent picture of what happens internally.

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 dense with critical information. It is front-loaded with the core purpose, then moves to usage context, a pairing recommendation, and technical details. Every sentence earns its place—no fluff or repetition. The structure naturally guides the reader from 'what' to 'when' to 'how.'

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

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

Even without an output schema, the description fully explains what the agent can expect: 'top-N passages with character offsets and similarity scores.' It covers constraints (200K cap, truncation flag) and integration with a sibling tool. For a search utility, this provides all necessary context for the agent to use it correctly.

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

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

The input schema covers all parameters with descriptions (100% coverage), so the baseline is 3. The description reinforces the schema by giving a natural-language example for 'query' and specifying the text input as 'text you already pulled.' However, it doesn't add meaning beyond what the schema already provides; the examples are helpful but not essential.

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: 'Semantic search INSIDE a fetched record.' It specifies the input (text + query), the output (top-N passages with offsets and similarity scores), and provides a concrete example (SEC 10-K body). It distinguishes itself from sibling tools by focusing on searching within an already-fetched text rather than general research or Q&A.

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

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

The description explicitly states when to use this tool: 'Use when the record is too big to cram into the prompt.' It explains the benefit ('saves context, returns only the passages that matter') and even provides a pairing with ask_pipeworx_grounded, showing a clear workflow. This gives the agent strong guidance on when to invoke it 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?

The description discloses significant behavioral details: OAuth requirement, delivery channel constraints (10/day SMS cap), webhook auto-disable after 10 failures, and one-time signing secret. These go beyond the annotations (readOnlyHint=false, idempotentHint=true) and provide rich context.

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

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

The description is long but well-structured, moving from purpose to requirements, types, and delivery channels. Every sentence contributes unique information, and the core action is front-loaded.

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

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

It covers purpose, auth requirements, all five subscription types, delivery options, return value (subscription id), and limitations. Even without an output schema, the description gives the agent enough context 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?

Although the schema covers 100% of parameters, the description adds practical semantics: type-specific examples (e.g., items:['5.02'] for officer changes), E.164 phone format, and webhook signing details. This supplements the schema meaningfully.

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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' The verb and resource are specific, and the tool is distinguished from siblings like list_subscriptions and unsubscribe.

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

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

It explains when to use the tool (to create proactive subscriptions) and contrasts it with pulling from the always-on feed via recent_alerts. It also gives prerequisites such as requiring a Pipeworx OAuth account and verified phone for SMS, without explicitly naming alternatives for management tasks.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, so safety is covered. The description adds meaningful behavioral context beyond annotations: it states the output is 'category-bucketed example questions... drawn from the live catalog of thousands of tools', which sets expectations about freshness and content. 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 on the longer side, but every part earns its place: usage examples, core purpose, output details, and invocation guidance. It is front-loaded with natural language queries that quickly orient the reader. A slight miss on perfect conciseness due to the lengthy example list, but overall well structured.

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

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

For a tool with one optional parameter, no output schema, and strong annotations, the description covers all necessary context: when to use it, what it returns, how to customize, and relationship to meta-tools. The openWorldHint and non-destructive annotations further complete the picture. Nothing critical is missing.

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

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

Schema description coverage is 100%, as the schema already documents the 'topic' parameter's allowed values and the 'omit for cross-category' behavior. The description reinforces this with examples like 'finance', 'pharma', 'betting' but adds no new semantic info beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states this is 'the onboarding entry point' that returns 'category-bucketed example questions' with exact tool+argument shapes. It uses specific verbs like 'suggest' and 'returns', and distinguishes itself from sibling tools by positioning itself as the first thing to use when unfamiliar with Pipeworx. This is a precise, non-tautological purpose.

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

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

Explicitly instructs when to use it: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also explains parameter usage ('Call with no arguments for the full spread, or pass topic to focus') and hints at alternatives by listing meta-tools to learn about. Clear contextual 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 idempotentHint and destructiveHint, but the description adds valuable context about ownership enforcement and the soft-delete behavior (deactivated, not deleted). This goes beyond the structured 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?

Two efficient sentences front-load the action and then add the key ownership and deactivation details. No wasted words; every clause 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 single-parameter mutation tool with annotations and no output schema, the description covers the essential behavioral contract: what is canceled, who can cancel, and what happens to historical data. This is complete and well-scoped.

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

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

The schema already provides 100% coverage by describing the id as 'Subscription id (uuid) returned by subscribe.' The description's 'by id' adds no additional semantic value, so it appropriately rests at 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 a specific verb and resource: 'Cancel a subscription by id.' This clearly distinguishes the tool from siblings like subscribe and list_subscriptions, and adds meaningful detail about deactivation versus deletion.

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: ownership is enforced and only your own subscriptions can be canceled. It also implies when to use recent_alerts for historical access after deactivation, though it does not explicitly mention alternatives like list_subscriptions for finding ids.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds substantial behavioral nuance: routing to sources, emission of verbatim evidence with pipeworx:// citations, the full verdict enum, and the crucial distinction between could_not_verify (check did not happen) and unsupported (no source exists). This goes well beyond annotations and gives agents the interpretation they need to act correctly.

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

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

The description is dense and information-rich, front-loaded with purpose and usage. It is somewhat long, but each clause earns its place, providing examples, route-specific behavior, return values, warnings, and even a performance note. The structure is mostly linear and readable; a slight tightening of the opening phrasing would make it fully concise, but it is far above average.

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 2-parameter tool with no output schema, the description is exceptionally complete. It specifies the return verdict enum, evidence/citation format, error semantics for could_not_verify, and the unsupported case. It also covers both supported claim types (financial vs. other) and the tolerance behavior. There is no ambiguity left for an agent.

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

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

Though schema coverage is 100%, the description enriches both parameters significantly. It provides a concrete example for claim, explains that tolerance_pct has a 0.5–50 range, defaults to wording-implied with a 5% cap, and notes that 1–2% is appropriate for hallucination detection—details not in the schema. This gives agents precise guidance for setting tolerance.

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 natural-language claim verifier that returns a verdict against authoritative sources, with concrete example phrases ('fact check', 'verify the claim that…'). It distinguishes itself from sibling Q&A tools by focusing on verification with evidence and structured verdicts, and by explicitly describing the two routing paths (SEC EDGAR for financial claims, grounded pipeline for others).

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

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

It explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further differentiates company-financial claims from other factual claims, explains the automatic routing, and warns about the interpretation of could_not_verify. It also notes that the tool replaces 4–6 sequential calls, giving the agent a strong usage heuristic.

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