Stat Gl

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: the default free model, the BYO-key billing implication for Anthropic, and the return payload structure. 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?

Three sentences with no filler. The core function is front-loaded, followed by cost/model details and use cases. Every sentence contributes essential information.

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

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

With no output schema, the description explains the return format per model and the combined view. It also covers main use cases, input entity type, model selection, and billing implications, making it sufficiently complete for an agent to decide on usage.

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

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

Schema coverage is 100% for all 4 parameters, so the baseline is 3. The description reinforces the conditional need for _apiKey when 'anthropic' is in models and confirms the default model, but it doesn't add significant new meaning beyond 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 clearly states the tool probes one or more LLMs about a business/brand/topic and returns a 0-100 visibility score per model. It specifies the verb (probe), resource (LLMs), and output (score, confidence, signals, raw_response), which distinguishes it from siblings like 'scan_competitor_ai_presence' by focusing on per-model scoring.

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 (AI-marketing audits, pre-launch brand checks, competitive monitoring) and clarifies when to use the free default model versus providing an Anthropic API key. However, it doesn't name alternatives or state when not to use this tool, so it stops short of full exclusion 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 indicate read-only, idempotent, non-destructive, open-world. The description adds substantial behavioral context: routing across thousands of tools, filling arguments, returning citations, working on every tier, and being one fast call. No contradiction with annotations.

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

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

The description is long but front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and information-dense throughout. The examples and alternative tool guidance justify the length, though it could be trimmed slightly without losing 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?

Despite no output schema, the description clearly explains what the tool returns (structured answers with stable citation URIs). It covers scope, usage triggers, exclusions, and escalation paths, making it complete for a high-complexity meta-tool with 6 parameters.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific semantics beyond the schema, but the schema already documents 'question' and its aliases with examples. The description's mention of 'fills arguments' is generic.

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

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

The description clearly states a specific verb+resource: it routes questions to one of 5,529 tools across 1,455 verified sources, fills arguments, and returns structured answers with pipeworx:// citations. It also distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit usage guidance: 'PREFER OVER WEB SEARCH', 'Use whenever...', 'START HERE for most questions', and explicitly names alternatives for when to step up (ask_pipeworx_grounded, deep_research). Each scenario is clearly delineated.

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

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

The description goes well beyond the annotations by disclosing the beta status, the live candidate testing mechanism, the current inactive state (last retirement date), and that it is a fully functional router with no fallback. This adds rich behavioral context that annotations alone do not provide, and it aligns with the read-only/idempotent hints.

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

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

The description is well-structured and front-loaded with the core identity ('Beta version of ask_pipeworx'), then efficiently covers behavior, current state, and usage in four sentences. Every sentence earns its place, with no redundancy or filler.

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

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

Given the tool's complexity as a beta router with no output schema, the description provides complete context: its relationship to the stable ask_pipeworx, the experimental nature, the current state of no active candidate, and explicit usage guidance. An agent has all necessary information to decide when and how to invoke this 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 covers 100% of the parameters, documenting six aliases for the same 'question' field. The description merely states 'same arguments' without adding new semantic detail beyond what the schema already provides. Since schema coverage is complete, the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router, and distinguishes it from the stable version by explaining its experimental routing candidate feature. It names the specific resource and the verb 'ask' implicitly, and the context ('Beta version of ask_pipeworx') situates it among siblings.

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

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

The description explicitly states when to use the tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the comparison against the stable router, making the experimental context clear. However, it does not explicitly state when NOT to use it (e.g., for stable/production needs), leaving the alternative slightly implied rather than directly stated.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses key behaviors: refusal reasons on failure, return format with evidence/confidence, and the 'ONLY what the tool result contains' extraction constraint. This adds substantial context about edge cases and reliability beyond what annotations or schema provide.

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

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

The description is dense but well-organized, front-loaded with 'Hallucination-resistant answer mode for high-stakes reads.' It efficiently packs routing details, return format, refusal reasons, and usage guidance without excessive verbosity, though slightly long due to the refusal list with five reasons.

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

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

Despite no output schema, the description fully specifies the success and refusal return structures, including refusal reason enums. It also explains the routing breadth (5,529 tools) and cost implications, making the tool's behavior sufficiently complete for an agent to invoke and interpret results.

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

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

Schema coverage is 100% with the 'question' parameter fully documented including aliases. The description adds no further parameter-specific meaning, but the baseline of 3 applies since schema already handles parameter semantics completely.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode that extracts answers only from tool results. It distinguishes itself from sibling ask_pipeworx by emphasizing grounded extraction and evidence-based responses, and contrasts with other tools for high-stakes reads.

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

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

Explicit when-to-use guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on...' with concrete examples. It also specifies when not to use it ('prefer ask_pipeworx for casual lookups') and the cost tradeoff, offering clear selection criteria 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?

The description goes well beyond the annotations, disclosing resolver contracts (market_match_confidence, alternatives, suggestions), safety short-circuit behaviors (low_confidence_match, market_closed_or_inactive), liquidity warnings (illiquid_wide_spread), and resolution-rule risk (cancellation_rule parsing). This level of detail is exceptional and directly helps the agent understand quirks and failure modes. No contradiction with the readOnly/openWorld/idempotent hints 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 extremely long and dense, but it is clearly structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESOLVER CONTRACT, etc.) and concrete examples. It could be more concise; the fan-out examples and verbose explanatory sentences could be trimmed without losing essential info. Structure is good, but conciseness is a weakness.

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

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

Given the tool's complexity and lack of an output schema, the description is remarkably complete. It explains response shapes, evidence keys, resolver behavior, parent-event extraction, news fallback handling, and cancellation-rule parsing. An agent has everything needed to set expectations and handle edge cases.

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

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

The input schema already describes all three parameters with 100% coverage, including defaults and formats. The description adds no new parameter-level semantics beyond what the schema provides; it merely reinforces examples. The baseline for high schema coverage is 3, and since the description doesn't compensate with extra param details, that baseline holds.

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 what the tool does: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It names the specific resource (Polymarket bet), the action (research, resolves, classifies, fans out), and distinguishes itself from related sibling tools like polymarket_edges or validate_claim by emphasizing full evidence-packet retrieval. The 'Use for' line further sharpens the 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?

The description explicitly provides use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This communicates when to apply the tool. It does not name explicit alternative tools to prefer in other cases, but given the sibling list, the guidance is sufficient for an agent to select it appropriately.

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

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

Annotations already declare readOnly, openWorld, and idempotent. The description adds significant behavior: pulls from SEC EDGAR/XBRL and FAERS, specifics on metrics (revenue, net income, cash, debt; adverse-event counts, approvals, trials), correct handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. This far exceeds annotation coverage 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 dense but every sentence earns its place. It front-loads query examples, then states core purpose, then type-specific data sources, and closes with sorting and return format. 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 appropriately explains what the tool returns (paired data, citation URIs, sorted results). It covers both entity types and their data sources, and also explains the efficiency advantage over sequential lookups. The description is complete for the tool's complexity.

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

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

Although the input schema has 100% coverage for parameters, the description deepens meaning: it explains exactly what each 'type' retrieves, provides concrete examples for 'values' (AAPL/MSFT, ozempic/mounjaro), and notes off-calendar fiscal year behavior. This is genuinely additive guidance.

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 ('side-by-side comparison') and clearly identifies the resource (2–5 companies or drugs). It distinguishes itself from sibling tools like entity_profile by emphasizing 'ONE parallel call' and showing natural-language trigger phrases. The scope is fully clear.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing an unambiguous when-to-use directive. It also lists example queries that should invoke this tool, making the usage context unmistakable.

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

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

Beyond the annotations (read-only, idempotent, open-world), the description discloses auth/plan requirements, parallel tool routing, decomposition into facets, the findings packet structure (evidence + confidence + source + fetched_at + citation), explicit gaps[] never invented, hop re-angles, semantic excerpting, and latency ranges. No contradiction with annotations.

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

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

The description is long but information-dense; every sentence earns its place. It front-loads the critical account requirement and the alternative tool. It could be slightly more structured, but 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?

Given there is no output schema and the tool is highly complex, the description fully compensates by explaining the return packet, gaps[], contradictions[], hop field, citation_uri semantics, and expected execution times. It leaves no major behavioral gap for an agent to infer blindly.

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

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

Schema coverage is 100% and both parameters are already described in the input schema: 'question' as natural language and 'depth' enum with per-value behavior. The description adds no substantive parameter-level meaning beyond the schema, 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 states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call. It further differentiates from siblings by explicitly calling out that it is 'NOT open-web search' and contrasts with ask_pipeworx, making the unique value unmistakable.

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

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

Usage guidance is explicit and rich: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead.' This clearly states when to use this tool and when to switch 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 disclose readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context by describing the return format: 'names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This tells the agent exactly what to expect from the output, beyond what annotations provide.

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

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

The description is efficient and front-loaded with the core purpose. The extensive list of data domains is somewhat verbose but serves the practical purpose of helping users formulate queries. The second sentence adds essential output details and usage guidance. No filler words, though the domain list could be trimmed for extreme conciseness.

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

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

Given that there is no output schema, the description fully compensates by detailing the return value: tool names, descriptions, full input schemas, and curated examples. It also covers the decision-making context ('Call this FIRST') and the breadth of domains. For a read-only discovery tool with strong annotations, this description is complete and well-suited for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions 'describing the data or task' which aligns with query parameter, but does not add detail beyond the schema's own descriptions of query and aliases. The concept of 'top-N' subtly references the limit parameter, but no new semantic information is provided in the 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's function: 'Find tools by describing the data or task.' It goes beyond a generic verb+resource by enumerating specific data domains (SEC filings, FDA drugs, FRED, etc.), which distinguishes it from all sibling tools that are domain-specific or task-specific. No ambiguity about what this 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?

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist,' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context and an implicit exclusion (if you know the exact tool or need a single answer, you wouldn't use this).

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 reveals it fans out across multiple data sources in parallel, details specific output fields such as recent_filings with URIs and fundamentals sorted by period_end, and discloses the USPTO patent API sunset and GDELT→GNews fallback. This provides critical 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 long but logically organized: example queries, purpose, usage preference, source list, output breakdown, and input constraints. It repeats 'names not supported' but overall every section contributes necessary detail for a complex multi-source 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?

With no output schema, the description thoroughly explains what will be returned (cik, company_name, recent_filings with URIs, fundamentals with specific metrics, patents with status, news with fallback, LEI). It also covers input requirements and behavior, making it 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?

The input schema already describes both parameters (type enum 'company' and value as ticker or zero-padded CIK). The description adds concrete examples ('AAPL', '0000320193') and reinforces the zero-padding requirement, going beyond the schema's basic 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 opens with concrete example queries ('Tell me about X') then states the core function: 'full cross-source profile of a US public company in ONE parallel call.' It clearly identifies the resource (US public company) and the action (profile), and distinguishes from single-pack lookups by advising to prefer it over chaining.

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 to 'ALWAYS PREFER' this tool over chaining individual SEC/XBRL/news lookups when the user wants a holistic view. It also states that only ticker or zero-padded CIK are accepted and directs to use resolve_entity first if only a name is available.

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 destructive and idempotent behavior. The description adds context beyond those hints by explaining why deletion might be needed (clearing sensitive data, stale context). It does not contradict the annotations.

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

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

The description is two sentences, front-loaded with the specific action ('Delete...'), and every clause provides useful guidance (when to use, pairing). There is no filler 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 1-parameter delete tool with strong annotations, the description covers what it does, when to use it, and how it relates to sibling tools. No output schema exists, but return values are less critical for a delete operation. A note about whether deletion is permanent or reversible would be helpful but is not essential given the destructiveHint.

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 parameter 'key,' so the description does not need to add detail. It only says 'by key,' which matches the schema. No additional semantics or format guidance are provided, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Delete a previously stored memory by key.' This clearly differentiates the tool from its siblings 'remember' and 'recall,' which handle writing and retrieving memories, respectively.

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: 'Use when context is stale, the task is done, or you want to clear sensitive data...' It also suggests pairing with remember and recall, which indicates complementary tools. However, it does not explicitly state when not to use the tool, which would push it to 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 the tool as read-only, open-world, idempotent, and non-destructive. The description adds useful behavioral context: it fetches the page, extracts title/description/key links, and emits a single text blob. This explains what the agent can expect beyond the safety profile, such as network access and specific output structure. Not as rich as some tools but sufficient for the simple operation.

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 plus a compact 'Useful for' list. It front-loads the primary action and output, then lists concrete use cases. No filler or repetition of schema/annotation info. Every sentence earns its place, making it easy to scan and understand quickly.

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

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

For a tool with two params and no output schema, the description is complete. It covers the tool's function, process (fetch, extract, emit), output format (text blob ready for llms.txt), and three distinct use cases. Annotations cover safety and idempotency, and the schema covers parameters. No significant gaps remain for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, with both url and max_links clearly documented in the schema. The description itself doesn't add parameter-specific details (e.g., default max_links=25), but the schema already covers meaning. This meets the baseline for adequate schema documentation, with no additional semantics needed from the 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 opens with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL'. It clearly distinguishes itself from sibling tools by focusing on generating a standard file format, not just checking visibility or scanning competitors. The exact output (standard llms.txt markdown) and trigger (AI crawlers) provide clear purpose.

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

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

Provides explicit use cases in the 'Useful for' list: getting a client's site indexed, drafting for own project, auditing competitor visibility. This gives clear context for when to use, but doesn't explicitly mention alternatives or exclusions, such as 'use scan_competitor_ai_presence instead for a full audit'. Slightly below a 5 due to lack of when-not guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the bar is lower. The description adds context by specifying that only active subscriptions are returned by default and by enumerating the exact return fields, which goes beyond the annotations.

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

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

Two sentences: the first states the action and return fields, the second explains when to use it. Every word is purposeful, and the most important information 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?

For a simple list operation with one optional parameter, the description covers the purpose, return shape, and usage context. The rich annotations compensate for the lack of an output schema, and note that return values are explicitly listed in prose.

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

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

Schema coverage is 100% for the single boolean parameter 'include_inactive', which is already well-described in the schema. The description's mention of 'active subscriptions' reinforces the default behavior but does not add new semantic detail beyond the schema.

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

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

The description uses a specific verb ('List') and resource ('the caller's active subscriptions'), and explicitly lists the returned fields, making the tool's purpose unambiguous. It also differentiates from sibling tools like 'subscribe' and 'unsubscribe' by positioning itself as a review step before adding or canceling.

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 when-to-use guidance: 'to review what you're monitoring before adding more or to find an id to cancel.' It implies these are the contexts for using this tool, though it doesn't explicitly name alternative tools to use instead.

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

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

Beyond the annotations, the description discloses behavioral details: rate limiting ('5 per identifier per day'), the claim_token flow for later lookup, that it's free and doesn't count against quota, and that the team reads digests daily. 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 every sentence earns its place: purpose, usage conditions, exclusions, token flow, rate limit, quota note. It is front-loaded with the core purpose and wastes no 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?

Given the tool's complexity (nested context, no output schema, optional params), the description is fully sufficient. It covers return behavior via claim_token, rate limits, boundaries, and practical guidance on formatting feedback. A model could use this tool correctly with no additional information.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the claim_token usage pattern with a concrete example ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and clarifying the type enum, though it doesn't add much beyond the schema for the context object.

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 ('Tell the Pipeworx team') and enumerates the kinds of feedback (bug, feature, data_gap, praise). It is immediately distinguishable from sibling tools, which are all research/query tools.

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

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

The description provides explicit when-to-use criteria ('Use when a tool returns wrong/stale data...') and an explicit when-not-to-use with an alternative ('if the tool came from a different MCP server... file it with that server instead'). This is textbook usage guidance.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description goes further by revealing the data provenance (CF analytics-engine), privacy guarantees (no PII), and caching behavior (5min-1h), which are not captured in annotations.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by output details and a compact bulleted usage list. It's slightly verbose in the 'Useful for' section but each element contributes value, earning a solid structure rating.

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

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

Despite lacking an output schema, the description explicitly states the return contents (top tools, top packs, total call volume). It also covers caching and privacy context, making the tool's behavior predictable for an agent. The absence of error handling or edge-case details is acceptable for a read-only aggregation 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 single optional parameter 'window' is fully documented in the schema with its enum values and semantics (shorter windows for hot trends, longer for steady-state). The description adds no additional parameter-specific information, so it neither compensates nor falls short—the schema carries the weight.

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

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

The description explicitly states the tool's function: reporting what other AI agents are calling on Pipeworx, with specific outputs (top tools, top packs, call volume). It distinguishes itself from sibling tools like ask_pipeworx or discover_tools by focusing on aggregate trending data rather than individual queries or search.

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

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

The 'Useful for' list explicitly outlines three concrete scenarios for using this tool, such as discovering hot data sources or confirming canonical tool choices. While it doesn't name alternative tools to avoid, it provides clear contextual guidance on when this tool adds value.

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 richly details behavior beyond annotations: the partition filter (drops placeholder slugs, null arb for >20% placeholders), the fill check (prices against live CLOB depth, warns when realizable_edge_pp ≤ 0), and the semantic anchor (Jaccard similarity threshold, skipped_low_similarity). These are critical behavioral traits not conveyed by readOnlyHint or idempotentHint.

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

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

The description is long (roughly 300 words) but uses clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the core purpose. Every sentence adds value, though the overall length pushes the boundary of conciseness.

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

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

Given the tool's complexity (two modes, no output schema), the description is highly complete: it explains the response structure (opportunities[], partition_check{}), mentions skipped_low_similarity, placeholders_filtered, and provides actionable trading guidance (when realizable_edge_pp ≤ 0, do not trade). This covers all essential context an agent would need.

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

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

Although schema coverage is 100%, the description adds substantial meaning: it explains event slug formats, topic seed questions, what each mode does internally (walks child markets, flattens markets, runs comparator), and the distinction between event and topic modes. This goes far beyond the schema's basic parameter names and descriptions.

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

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

The description opens with a specific verb+resource statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly names the tool's purpose and distinguishes it from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection and fill validation.

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

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

The description provides explicit usage modes: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also references an alternative tool: 'For custom sizing use polymarket_fill_risk.' This gives clear when-to-use guidance and alternatives.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses substantial behavioral traits: caching ('Cached 1h at the KV level keyed on all knobs'), response structure with diagnostics ('_diagnostics... so callers can see WHY a segment is empty'), model-family gates (e.g., 'partitions with >20% placeholder fraction skipped entirely'), and edge-quality filters including a 24h-move warning. This is far beyond the structured fields and gives the agent a clear model of runtime behavior.

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

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

The description is dense and comprehensive, which is justified given the tool's complexity and lack of an output schema. However, it is a very long, single-block paragraph with heavy use of capitalization, parentheses, and semicolons, making it harder to parse quickly. Every sentence provides useful detail, but the structure could be improved with bullets or clearer segmentation, so it is not a model of conciseness.

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

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

Despite having no output schema, the description fully explains the response shape at the top level ('by_segment{model_driven,structural_arbitrage,concentrated_longshot}'), the fields on each opportunity ('edge_pp_net, kelly_fraction + kelly_fraction_half, market.liquidity, market.spread_pp, market.volume'), and the diagnostics object. It also covers model families, filtering logic, cache behavior, and why some segments may be empty. This is complete for the tool's complexity.

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

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

Schema description coverage is 100%, with each parameter already fully documented including defaults, examples, and rationale. The description adds some parameter context by explaining how knobs affect tradeability (e.g., 'min_liquidity / max_spread_pp drop opportunities where edge isn't realizable'), but this largely restates the schema rather than adding new semantic value. It does not need to compensate for missing schema info, so a baseline of 3 is appropriate.

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

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

The description explicitly states the tool's function with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also positions the tool for a clear use case ('what should I bet on today') and differentiates it from generic market listing by mentioning model families and segments, which distinguishes it from sibling tools like polymarket_arbitrage.

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

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

The description provides clear usage context through 'Built for "what should I bet on today"' and explains that agents discover opportunities without paging hundreds of markets. It includes practical caveats such as Fed bets being excluded from ranking and longshot opportunities being 'rare-by-design', but it does not explicitly name alternative tools or state when not to use it.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds substantial context beyond these: snapshots are only written on cache-miss (gaps mean no scan), history is bounded by a 60-day TTL, and decay is computed from daily closes net of default slippage. This clearly explains temporal quirks and data semantics, going well beyond the annotation hints.

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

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

The description is dense but well-organized with an opening summary, 'Args', 'RESPONSE', and 'LIMITS' sections. Every sentence contributes useful information, though the illustrative analogy about fresh vs. 3-week-old edges could be trimmed without losing core content. The length is justified given the complexity and lack of an output schema.

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 documents the response structure: tracked[], expired[], and snapshot_dates[], including field meanings like edge_pp_net sign convention and decay metrics. It also covers data gaps, TTL limits, and computation basis, making it complete enough for an agent to understand what results to expect and how to interpret them.

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

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

The input schema already covers both parameters fully with defaults and clamps. The description adds meaning by explaining that 'window' selects the snapshot family (24hr | 1wk | 1mo) and 'days' controls lookback, reinforcing real-world significance. It does not introduce new schema fields but clarifies the role of parameters in the context of snapshotting behavior.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry built from daily polymarket_edges snapshots. It explicitly names the core question it answers ('how long has this edge existed and is it shrinking?') and distinguishes it from sibling tools like polymarket_edges by focusing on time-series trends and lifecycle rather than current edge values.

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

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

The description provides clear context on when to use the tool: to analyze edge persistence over time and detect decay. It implicitly contrasts with fresh edge data via the example of a 3-week-old wide edge. However, it does not explicitly name alternative tools or state 'use X instead when,' so exclusions are only implied rather than direct.

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

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

While annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, the description adds substantial context: it details how the tool walks the order-book ladder, returns specific fields like slippage_pp and forced_directional_risk, interprets size_usd differently per mode, clamps values, and warns about partial fills and unhedged positions. This goes far beyond the annotation-provided safety profile.

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

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

The description is long but every sentence earns its place given the tool's complexity. It is well-structured: a one-line core purpose, a REQUIRES clause, distinct SINGLE-MARKET and BASKET sections, and a final usage directive. The front-loaded summary ensures the agent grasps the primary function immediately, while subsequent details justify the length.

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

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

With no output schema, the description fully covers return values for both modes, listing outputs such as top_of_book, vwap_fill_price, capture_ratio, per-leg fill detail, and forced_directional_risk. It also addresses edge cases (thin_legs, partial fills) and provides usage context, making the tool complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, but the description adds significant semantic value. It explains that `market` enables single-market mode and `event` enables basket mode, clarifies that `side` has mode-specific options (buy_yes/sell_yes in basket, auto default), and redefines `size_usd` as 'max spend on buys, target proceeds on sells' for single-market and 'settlement notional' for basket, including default and clamp behavior.

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

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

The description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' a specific verb+resource statement that clearly defines the tool's function. It goes on to describe two distinct modes (single-market and basket) and lists concrete outputs, distinguishing it from siblings like polymarket_arbitrage and polymarket_edges by emphasizing fill risk and realizable versus theoretical edge.

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 final sentence explicitly instructs when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial basket fills convert arb into directional risk), providing clear context and exclusions implicitly.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the safety logic in detail: compatibility_warning conditions, temporal_alignment semantics, and skipped_cross counters. It explicitly states cases where spreads are 'mathematically meaningless' and warns that a lack of token-overlap may indicate unrelated events. This is rich behavioral context that annotations alone don't provide.

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

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

The description is front-loaded with the core purpose, then uses ALL-CAPS headers (TWO MODES, RESPONSE, SAFETY FIELDS) to organize detailed behavioral info. While it is quite long and includes redundant examples (e.g., topic list appears in both schema and description), it remains well-structured and mostly avoids fluff. A slightly tighter wording would earn a 5.

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

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

With no output schema, the description takes on the duty of explaining the response shape, covering leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, and skipped_cross counters. It also addresses edge cases for non-equivalent bet shapes and unrelated events. This is sufficient for an agent to invoke the tool and interpret results.

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

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

The schema already documents all three parameters with descriptions, but the tool description adds the two-mode semantics and override relationships: topic auto-fetches matching events, while explicit ticker/slug override the topic-mapped side. It also clarifies that all parameters are optional, which is implicit in the schema. This adds meaningful context beyond the structured field descriptions.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question', which clearly identifies the tool as computing a cross-venue price delta. It distinguishes from sibling tools by naming both venues and adding the caveat about bet-shape equivalence, clarifying that it only reports real signals when shapes match.

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 outlines two usage modes (topic shortcuts vs explicit ticker/slug) and explains when the spread is meaningful ('when the bet shapes are equivalent'). It warns that 'most pre-mapped topics return compatibility_warning today' and that 'pre-mapped ≠ tradeable', guiding users on when not to rely on the output. However, it does not explicitly name alternative sibling tools for other tasks, so it lacks explicit alternative comparison.

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

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

Annotations already provide readOnly, idempotent, and non-destructive hints. The description adds valuable behavioral context: the POST requirement, the exact body structure, the response format json-stat2, and the risk of large-table rejection for empty queries. 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?

Two sentences deliver the essential purpose, body template, and usage caution. No filler words; every clause contributes actionable guidance.

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 returns json-stat2 but has no output schema, so the description's mention of 'observations as json-stat2' covers the return contract. It also explains the body format, path example, large-table rejection risk, and recommends table_meta for codes, making the description self-sufficient for a query 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?

Even though schema coverage is 100%, the description enriches both parameters: it spells out the exact body schema '{query:[{code, selection:{filter,values}}], response:{format:"json-stat2"}}' and clarifies the path with an example. It also explains behavior (empty query behavior) not present in the schema.

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

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

The description opens with a specific verb-resource pair: 'POST a PxWeb query to a Statistics Greenland table and return observations as json-stat2.' It clearly identifies the operation, target, and output format, distinguishing it from sibling tools like table_meta (metadata vs. data).

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

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

'Narrow selections using codes from table_meta' explicitly directs the agent to a sibling tool for codes and warns against empty queries for large tables. This provides practical usage context, though it does not fully enumerate when to use query_table over competing tools.

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

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

With readOnlyHint and destructiveHint annotations already declaring a safe read operation, the description adds valuable context: it explains the dual behavior (retrieve vs list), scoping to the agent's identifier (IP, key hash, or account ID), and the omission-to-list-mode. However, it doesn't disclose behavior for missing keys or pagination, though those are minor.

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 packed with relevant information. The first sentence states the main action and both modes, the second gives a concrete use case, and the third adds scoping and complementary tools. No filler or redundant content.

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

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

For a simple tool with one optional parameter, no output schema, and strong annotations, the description fully covers the two usage modes, scoping behavior, and relationship to sibling tools. There is no missing context that an agent would need to invoke it correctly.

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

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

The schema already provides 100% coverage for the single key parameter, so the baseline is 3. The description enriches this by explaining the key is for retrieving a single value while omitting it lists all keys, and gives concrete examples of what keys might represent (target ticker, address, research notes), adding practical meaning.

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

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

The description explicitly states the tool retrieves values previously saved via remember or lists all saved keys, with a clear verb-resource pairing. It differentiates itself from related tools by naming remember and forget as the complementary save/delete counterparts.

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 a specific use case: looking up previously stored context like a ticker, address, or research notes without re-deriving it. It also implicitly advises when to use this tool (when context was saved earlier) and when not to (re-deriving), plus names the complementary tools remember and forget.

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 though annotations already declare readOnlyHint and idempotentHint, the description goes further by disclosing the optional mark_read side effect ('flag returned events read so the next call only shows newer ones') and describing return fields like source and citation_uri. This adds context beyond the structured annotations and avoids any 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 three sentences, front-loaded with the core action, and every sentence adds useful information (purpose/return fields, filters, mark_read behavior/alternative endpoint). No filler or redundancy.

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

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

For a 5-parameter read tool with no output schema, the description covers the essential return format (payload fields), filter options, the read-state mutation, and even an alternative access method. Combined with full schema descriptions and safe annotations, this is highly complete.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The description adds value by providing an example type filter ('sec_8k'), clarifying the ISO timestamp format for 'since', and explaining the practical effect of mark_read (affects subsequent calls). This is above baseline, though not exhaustive for all parameters.

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

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

The description opens with 'Pull fired events from your subscription feed.' This is a specific verb+resource statement that clearly distinguishes it from siblings like list_subscriptions (managing subscriptions) or recent_changes (change logs). It also specifies the return payload contents, making the tool's scope unambiguous.

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

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

The description gives clear usage context: it's for retrieving recent alerts from a persisted feed, with filtering by type and since. It also suggests polling is fine and mentions an alternative HTTP endpoint for scripts/dashboards. However, it doesn't explicitly call out when to avoid this tool or name direct alternatives from the sibling tool set, so it loses one 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?

Despite readOnlyHint/idempotentHint annotations already declaring safety, the description adds behavior beyond them: it discloses fans-out behavior to multiple sources, fallback logic (GDELT→GNews when rate-limited or 5xx), USPTO soft-fail due to PatentsView API sunset, and relative date parsing ('7d', '30d', '3m', '1y'). This is rich behavioral context the annotations don't provide.

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

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

The description is a single dense but well-organized paragraph, front-loads the query patterns in quotes, and every sentence adds information. It avoids restating the title or schema verbatim, and the length is appropriate for the tool's multi-source 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 zero output schema, the description compensates by explicitly listing return elements: structured changes[], total_changes count, pipeworx:// citation URIs. It also covers source behavior, fallback, and failure modes. The tool is complex (multi-source, two param formats, one enum), and the description addresses all of that with no ambiguity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains the `since` parameter's supported formats (ISO vs relative shorthand) and gives concrete examples. It also adds domain context for `value` (ticker or CIK) and notes the only supported entity type. Minor deduction because the schema already describes all parameters and the description's added value, while useful, is not exhaustive (e.g., no guidance on valid date ranges).

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 pair ('change feed for a company') and clearly distinguishes from sibling tools like entity_profile by explicitly contrasting what this tool does versus that static-profile tool. It names the exact data sources (SEC EDGAR, GDELT/GNews, USPTO) and the output shape, so purpose is unmistakable.

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

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

The description gives explicit guidance on when to use this tool: for 'What's new with X' / 'latest on Y' / temporal query patterns over the last N days/weeks/months. It also names an alternative (entity_profile) and states when to use that instead ('when you want the static profile... regardless of window'), satisfying the when/alternative test.

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 (which indicate a non-read-only, idempotent, non-destructive write), the description adds valuable behavioral context: memory is scoped by identifier, authenticated users get persistent storage, and anonymous sessions retain data for only 24 hours. It also explains the lifetime of the stored data and the relationship to recall/forget, all of which are not present in 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 tightly written in three sentences, each earning its place: the core purpose, when to use it with indicative examples, and storage/retention details. It's concise, well-front-loaded, and contains no filler or redundant information.

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

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

For a simple two-parameter tool with no output schema, the description fully captures the necessary context: purpose, use cases, storage scoping, retention period, and companion tools. It provides a complete mental model for how and when to invoke the tool, and the schema covers all parameters. 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 full descriptions for both 'key' and 'value' with examples, giving 100% schema coverage. The description mentions 'key-value pair' but adds no extra detail about parameter formats, constraints, or usage semantics beyond what the schema documents. Since the schema carries the load, this is a baseline score.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Save data the agent will need to reuse later.' It distinguishes itself from sibling tools by naming pairing with 'recall' and 'forget' and specifies the storage model (key-value pair, scoped by identifier). This makes the tool's role unambiguous.

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

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

The description gives explicit when-to-use guidance with concrete examples ('discover something worth carrying forward... a resolved ticker, a target address'). It also mentions pairing with recall and forget, which clarifies the workflow. However, it does not explicitly state when not to use the tool or contrast with alternatives beyond those two complements, so it stops short of full 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses graceful degradation for LEI/FIGI enrichment, explicit reporting of unresolved identifiers, and internal cascading through multiple endpoints. This adds significant behavioral context without contradicting annotations.

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

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

The description is longer than average but every sentence earns its place, with front-loaded examples and a clear breakdown of supported types. It is well-structured and avoids fluff, though slightly verbose for a tool description.

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 behavior including source labels, explicit unresolved fields, and graceful failure modes. It also explains the internal cascading and why this tool replaces multiple lookups, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances parameter meaning by explaining what 'company' entails (cross-source identity spine with CIK, ticker, LEI, FIGI) and what 'drug' returns (RxCUI, ingredient, brand), going beyond the brief schema descriptions. It doesn't introduce new parameter syntax but adds valuable background.

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 resolves a user-spoken NAME to canonical/official identifiers, with specific verbs like 'resolve' and 'look up'. It distinguishes from siblings by emphasizing that it provides IDs that other tools require as input, making it the go-to for name-to-ID conversion.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID', which gives clear guidance on when to invoke. It also provides examples of queries and notes it replaces 2-3 manual lookups, setting context for when this tool is preferable.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds meaningful behavior: probes each entity with ai_visibility_check, ranks by score, returns ranked list with score/confidence/signal density. It also notes which entity is most/least recognized. 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?

Three concise sentences with front-loaded purpose, no filler. Every sentence adds value: what it does, how it works, when to use it, and what it returns.

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

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

Despite no output schema, description specifies return content (ranked list with score, confidence, signal density). It covers purpose, use case, and operational details (probes with ai_visibility_check). Small gap: no mention of potential cost/rate limits for multiple probes, but overall sufficient.

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

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

Schema description coverage is 100%, so baseline 3 is appropriate. Description does not add significant parameter details beyond schema, but it reinforces that first entity is 'subject' and rest are competitors, which is also in schema.

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

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

Description uses specific verb 'Compare' with resource 'AI visibility across multiple entities side-by-side' and explicitly distinguishes from sibling tool which is single-entity check. It clearly states the workflow and output.

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

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

Provides clear context: 'Useful for competitive AI-marketing audits' and explains when to use this vs probing one entity. Does not explicitly name alternatives but references ai_visibility_check as the underlying mechanism, making usage context clear.

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

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

The description adds material behavioral context beyond the readOnlyHint/idempotentHint annotations: it discloses the composite fan-out, the 5-30s latency on first bundlephobia measurement, the graceful degradation with sources_failed, and the guarantee that the rest still returns. This is exactly the kind of operational nuance the annotation fields cannot convey.

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

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

The description is dense but well-structured: it front-loads the core purpose, then usage, then limitations and failure semantics. Every sentence adds information, though the final sentence is somewhat long and could be split for easier parsing. It earns a 4 for being efficient yet thorough.

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

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

With no output schema, the description compensates by enumerating the returned summary fields (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable) and noting per-advisory detail, links, and recent alternatives. It also covers edge cases (timeouts, partial failures) and ecosystem limitations, making it fully complete for a composite health-check tool.

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

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

Schema coverage is 100% with both 'package' and 'version' having clear descriptions. The tool description restates the npm-specific nature and default version behavior already in the schema, adding no new parameter-level details. Per the rubric, baseline 3 is appropriate when the schema carries the semantic load.

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-driven purpose: a composite 'should I add this npm package to my project' check. It names the exact sources (deps.dev and bundlephobia) and the data categories (license, advisories, bundle size, ESM support), making the tool's scope unmistakable and distinct from siblings like deep_research or validate_claim.

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?

Usage guidance is explicit: 'Use whenever an agent asks is X safe / popular / small or what does adding lodash cost me.' It also states a clear exclusion ('NPM ecosystem only in v1') and points to a direct alternative ('deps.dev:version directly') for other ecosystems, even naming the fallback behavior.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description goes beyond by disclosing return format (passages with offsets and similarity scores), the embedding model and window size (BGE-base-en, 500-char windows), and the 200K char cap with truncation flagging. This adds substantial behavioral context without contradicting annotations.

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

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

The description is information-dense but every sentence earns its place: the first establishes purpose, the second explains the use case and benefits, the third provides technical implementation details. It is front-loaded with the core purpose and structured logically without fluff.

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

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

Given no output schema, the description compensates by explaining the return shape (passages, offsets, scores). It also covers edge cases (truncation and flagging) and pairs with sibling tools. The 3-parameter tool is fully contextualized for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context for the text parameter with examples ('a SEC 10-K body, an article, a long tool result') and clarifies that the query is natural-language with illustrative examples. This goes beyond the schema's descriptions, though limit is not mentioned in the description.

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

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

The description clearly identifies the verb+resource: 'Semantic search INSIDE a fetched record.' It specifies the inputs (text + query) and outputs (top-N passages with character offsets and similarity scores). It also differentiates from siblings by noting it is for searching within a record, unlike ask_pipeworx_grounded which grounds over passages.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also provides an alternative/complementary tool: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear context and an exclusion for cases where the record fits in the prompt.

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, and non-destructive behavior. The description adds context by disclosing that an empty path returns root folders of type 'l' and tables of type 't', and that a sub-path drills deeper. It also notes the '.px' suffix, providing useful behavioral detail beyond the annotations.

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

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

The description is two sentences, front-loaded with the primary purpose, and each sentence adds necessary detail. It is concise and well-structured, with no wasted words.

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

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

For a simple navigation tool with one optional parameter and no output schema, the description covers the essential behavior: root vs sub-path, the meaning of table IDs, and how to proceed with other tools. It could mention the return format more explicitly, but the existing detail is sufficient given the tool's simplicity.

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

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

The schema already covers the 'path' parameter fully (100% coverage), including the default and an example. The description repeats this information and adds the behavior of empty vs non-empty paths, but doesn't significantly enhance the meaning of the parameter itself beyond what the schema provides. Thus the baseline of 3 is appropriate.

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

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

The description clearly states the tool 'browse the Statistics Greenland PxWeb subject tree', using a specific verb and resource. It distinguishes itself from siblings by explicitly mentioning how table IDs should be passed to table_meta or query_table, making its role as a navigation tool clear.

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

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

The description gives usage guidance by explaining the root vs sub-path behavior and providing an example like 'BE/BE01'. It also tells the agent to pass table IDs to table_meta or query_table, indicating alternatives, though it doesn't explicitly frame when to use subjects vs those tools.

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

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

Annotations indicate readOnlyHint=false and openWorldHint=true, and the description adds valuable behavioral details: account requirements, phone verification, SMS daily cap, and persistence constraints. No contradiction with annotations; the description complements them well.

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

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

The description is dense but well-structured: front-loaded purpose, then requirements, types, and delivery channels. Every sentence provides useful information, though the length is considerable. For a tool with multiple types and delivery options, this is appropriate and not wasteful.

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

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

Given the tool's complexity (3 params, nested objects, 5 types) and no output schema, the description covers critical aspects: return value, authorization prerequisites, supported types with examples, and delivery options. Webhook details are deferred to the schema, which is acceptable since schema descriptions are comprehensive.

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 concrete examples for several types (sec_8k, polymarket_edge, fred_series) and clarifies params structure (e.g., items codes, topic, series_id). It does not cover all types but schema descriptions fill the remaining gaps.

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 'Create a proactive monitoring subscription to a live-data event stream' and specifies the return value (subscription id). It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation, not listing or 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?

Provides clear usage context: requires a Pipeworx OAuth account, lists supported subscription types with examples, and explains the always-on feed channel with 'pull via recent_alerts' as the read mechanism. It implicitly contrasts with listing/unsubscribing tools but lacks explicit 'when not to use' 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 indicate a safe read-only, idempotent operation; the description adds valuable context about the output's structure (category buckets, exact tool + argument shape), the live catalog source, and the optional topic parameter's effect. 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 a dense, single-sentence block covering many aspects; while it's front-loaded with user intents and contains useful detail, it could be better structured with separate sentences or bullets. It's not wasteful, but it's longer than needed.

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 a single optional parameter and no output schema, the description is thorough: it explains the use case, invocation modes, result categories, and the nature of the content (exact tool + argument shape). This gives an agent everything needed 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 already provides a complete description of the `topic` parameter, including allowed values and omission behavior. The description repeats this with examples but adds no new semantics beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states this is the onboarding entry point for discovering what can be asked, returning category-bucketed example questions with exact tool and argument shapes. It explicitly differentiates from sibling tools like ask_pipeworx by framing it as the 'first' thing to call when unfamiliar with Pipeworx.

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

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

Explicitly instructs to use this tool FIRST when you do not know what Pipeworx can do, and mentions it helps learn how to call meta-tools. This provides clear when-to-use guidance and names alternatives, though it doesn't explicitly state when not to use.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds crucial behavioral context: the path must end in .px/.PX, that it returns dimensions with codes and value lists, and how the output is consumed. No contradictions.

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

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

Two sentences, each earning its place: first states the core purpose, second provides path constraints and usage guidance. No filler or redundancy.

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

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

For a simple tool with one parameter, good annotations, and no output schema, the description fully covers what it returns, how to invoke it, and how to use the result. Nothing important 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 covers the single 'path' parameter, and the description enriches it by specifying the full sub-path requirement and file extension constraint. This is essential information beyond the schema's generic example.

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 ('Fetch') and identifies the exact resource (dimension definitions and valid coded values for a Statistics Greenland PxWeb table). It clearly distinguishes from the sibling query_table by stating the output is used to build its selection body.

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 the tool (before query_table, to build its selection body) and provides a precise path format requirement with an example. The relationship to the sibling tool makes the intended workflow clear.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds meaningful behavioral context: ownership is enforced, and the row is deactivated not deleted so historical events remain available via recent_alerts. This enhances the agent's understanding of side effects and access control, beyond what annotations alone provide.

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

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

The description is two sentences long, front-loaded with the primary action, and every clause adds value: cancellation, ownership, deactivation, and historical event availability. No filler or redundancy; highly efficient structure.

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 low complexity (one parameter, no output schema, no nested objects), the description covers all essential aspects: what it cancels, who can use it, the exact side effect (soft delete), and the impact on historical data via recent_alerts. It is complete for safe and correct invocation.

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

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

The input schema already has 100% coverage for the single parameter id, describing it as a UUID returned by subscribe. The description merely repeats 'by id' without adding new semantic details, so it neither enhances nor harms the schema's clarity. Baseline 3 is appropriate.

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

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

The description uses a specific verb+resource ('Cancel a subscription by id') and clearly distinguishes from siblings like subscribe and list_subscriptions by noting the cancellation behavior and the deactivation (not deletion) aspect. It is unambiguous and immediately conveys 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 clear context ('Cancel a subscription by id', ownership enforcement, deactivation rather than deletion) that helps an agent decide when to use it. It does not explicitly name alternatives or when-not scenarios, but the connection to recent_alerts and the ownership constraint imply sensible usage boundaries. This is above the baseline but not a full explicit guideline.

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

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

The description goes well beyond the read-only/idempotent annotations by detailing the two processing paths, the full verdict set, and the critical distinction between could_not_verify and unsupported. It also warns callers not to treat could_not_verify as evidence, which is essential behavioral context not captured by annotations or schema.

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

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

The description is long but well-organized, with examples, process paths, return values, and caller warnings. Every sentence adds value, though it could be slightly tightened to improve scannability without losing important nuance.

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

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

Given the tool has no output schema, the description fully compensates by explaining the return verdicts, the meaning of special cases, and the fallback behavior across claim types. It is comprehensive enough for an agent to know exactly what to expect and how to handle results.

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

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

The schema already provides 100% coverage for both parameters, including detailed descriptions of tolerance_pct and claim examples. The tool description adds no additional parameter-level meaning beyond what the schema already contains, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It gives illustrative query examples and explicitly says it replaces 4–6 sequential calls, distinguishing it from sibling tools like ask_pipeworx or resolve_entity.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' which is a strong when-to-use directive. It also differentiates the SEC EDGAR fast path for company-financial claims from the grounded pipeline for other claims, but it does not mention explicit alternatives or exclusions.

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