Data Gov In

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable context about the default Workers AI model being free, the need for a BYO Anthropic API key, and the direct billing implication, which goes beyond the structured annotations.

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

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

The description is compact and front-loaded with the core action and output. Every sentence contributes: purpose, default behavior/cost, return format, and use cases. 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 the tool's moderate complexity and the lack of an output schema, the description covers all essential aspects: what it probes, scoring range, default vs. optional models, return structure, and practical use cases. It is fully self-contained 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 the schema already documents all four parameters. The description adds meaning by clarifying which model is default (workers-ai) and how _apiKey enables Anthropic probing, which supplements the schema's plain descriptions.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about an entity and scoring visibility (0-100) per model. It uses a specific verb ('Probe') and mentions distinct outputs, distinguishing it from sibling tools like ask_pipeworx or compare_entities.

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

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

The description provides clear usage context ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and notes the default model option. It stops short of explicitly naming alternative tools or exclusion criteria, so it doesn't fully earn a 5, but it does convey when to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds meaningful behavioral context: routing across 5,564 tools, filling arguments, returning citation URIs, and being a single fast call that works on every tier. 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 lengthy but well-structured: it starts with the key directive, then gives categories, examples, and alternatives in a logical flow. Every part adds useful guidance, though it could be trimmed slightly without losing 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?

For a complex routing tool with no output schema, the description fully covers what it returns (structured answer with citations), when to use it, and how it relates to alternatives. It also notes the tool works on every tier and handles breaking news routing internally, making it self-contained and complete.

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

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

Schema coverage is 100% (all parameters are aliases for 'question'). The description adds value by providing numerous examples of appropriate questions and trigger phrases, clarifying the intent of the question parameter beyond the schema's simple 'Your question or request in natural language.'

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: 'Routes the question to the right one of 5,564 tools... returns the structured answer with stable pipeworx:// citation URIs.' It uses specific verbs ('routes', 'returns') and explicitly distinguishes from siblings by naming ask_pipeworx_grounded and deep_research as alternatives.

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

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

Provides explicit when-to-use guidance with 'PREFER OVER WEB SEARCH' list of domains, trigger phrases ('what is', 'look up', 'get the latest'), and concrete examples. It also states when to step up to alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.'

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

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

Annotations already cover read-only, idempotent, and non-destructive hints. The description adds valuable context: candidate routing improvements are enabled live when under test, none are currently active, and it falls back to nothing (fully functional). This discloses the dynamic experimental behavior 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 front-loaded with the core purpose and then provides contextual details about current state and usage. It is slightly repetitive (e.g., 'currently matches ask_pipeworx exactly' plus 'No candidate is active right now') but each sentence contributes meaningful information.

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

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

The description is sufficiently complete for a complex beta router: it explains the experimental nature, current status, relationship to the stable version, and that it is a full working router. The only minor gap is that it references 'same response shape' without detailing what that shape is, but this is acceptable given the sibling ask_pipeworx context.

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

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

The input schema provides 100% coverage of all six parameters (aliases for 'question'), so the description does not need to add parameter detail. It only says 'same arguments' without elaborating, but the schema already carries the full 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 clearly identifies 'ask_pipeworx_beta' as a beta universal router identical to ask_pipeworx, with a specific scope (5,564 tools) and an explicit experimental nature. It distinguishes from siblings by positioning itself as the experimental edge of ask_pipeworx.

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

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

Explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. This provides clear when-to-use guidance and implies the alternative (ask_pipeworx) for stable routing.

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 fully discloses the behavioral contract: it returns a structured success object with evidence and refusal_reason:null, or an explicit refusal with enumerated reasons. It also discloses the cost trade-off ('Costs one extra LLM call vs ask_pipeworx'). This adds substantial value beyond the readOnlyHint/idempotentHint annotations and does not contradict them.

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

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

The description is dense yet well-structured: it begins with the core purpose, explains the mechanism, specifies the exact return shape and refusal reasons, then gives usage guidance and cost comparison. Every sentence earns its place; 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?

With no output schema, the description compensates by detailing the response structure, refusal reasons, and success/error semantics. It also explains when to use this over ask_pipeworx and provides the cost trade-off, making the description sufficiently complete for correct tool selection and invocation.

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

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

All 6 parameters are documented in the schema as aliases for 'question' with 100% coverage. The description does not add additional parameter-level semantics, but it also does not need to since the schema fully explains the natural-language question input.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads' and explicitly states it 'EXTRACTS the answer using ONLY what the tool result contains.' This clearly defines the tool as a grounded Q&A mode that returns evidence and refusals, distinguishing it from sibling ask_pipeworx.

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

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

Explicit guidance is given: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples (financial verdicts, legal claims, medical lookups, public statements). It also explicitly says 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description goes far beyond these by documenting resolver contract behavior (market_match_confidence, alternative matches), short-circuit statuses (low_confidence_match, market_closed_or_inactive), parent_event extraction, wide-spread illiquidity flags, and cancellation-rule parsing. It discloses critical behavioral nuances such as blocking paths and rule-based loss risks, with no contradiction to 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 structured with capitalized section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, RESOLUTION-RULE RISK). Each section provides operational value an agent needs, covering edge cases and response handling. The fan-out examples are illustrative rather than padding. Very dense but organized for easy scanning.

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 (multiple classifiers, fan-out behaviors, dynamic responses), no output schema, and only 3 parameters, the description is exceptionally complete. It documents response shapes (market, analysis, evidence), resolver contract fields, parent_event structure, news fallback flags, safety short-circuits, closed-market status, and cancellation-rule risk. It provides enough context to use the tool correctly across many scenarios.

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

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

The input schema has 100% coverage with detailed property descriptions for market, depth, and include_raw, including tradeoffs like response size and recommended false. The description adds no new parameter-level semantics; it simply echoes the market input format in examples and mentions include_raw behavior that is already fully documented in the schema. Thus it meets the baseline for high schema coverage but does not go beyond.

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

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

The description clearly states the tool's core function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' This provides a specific verb ('research'), resource ('Polymarket bet'), and scope (market query). However, it does not explicitly differentiate from sibling tools like polymarket_edges or validate_claim, which overlap in purposes like detecting edges.

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

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

The description includes explicit usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides detailed fan-out examples for various bet categories (BTC, Fed, Hormuz, Yankees, etc.). It lacks explicit when-not-to-use guidance or alternative tool recommendations, but the usage context is clear and actionable.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral context: it pulls specific data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. It also notes it replaces 8–15 sequential lookups, revealing performance characteristics.

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

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

The description is slightly long but front-loaded with practical examples and every sentence contributes unique value. It avoids repetition and uses clear formatting with trigger phrases, type specifics, and result behavior.

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 explains return format (paired data + citation URIs) and sorting order. Combined with the rich parameter details and sibling differentiation, it gives the agent a complete picture of the tool's behavior, including data sources and edge-case handling (off-calendar fiscal years).

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 both parameters with descriptions (100% coverage), but the description enriches them: type='company' triggers pulling specific financial fields from SEC EDGAR, while type='drug' pulls adverse-event and trial counts. This adds meaning beyond the schema's basic enum and value descriptions.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in a single parallel call, with specific examples of trigger phrases. It distinguishes itself from siblings by noting it should be preferred over sequential single-pack lookups for comparisons.

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

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

Explicit usage guidance is given: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also provides concrete query examples and defines the scope (2–5 entities), making it clear when to use this tool versus alternative approaches.

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/openWorld/idempotent annotations, the description discloses rich behavioral traits: expected latency (15-60s, up to 90s), gaps[] when data can't answer, contradictions[] scan for standard/thorough, citation_uri resolvability, semantic excerpting, account/paid plan requirements, and the fact it never invents evidence. 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 usage caveat (account requirement). Every sentence carries meaningful information, though citation behavior is mentioned twice (in the findings packet list and later via hop/citation_uri), and the long sentence structure is somewhat dense. Still, no filler and organization is logical.

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

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

With no output schema, the description fully covers the return value structure: findings packet with evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop field, and citation_uri. It also covers edge cases (unanswerable facets, empty gaps for out-of-catalog topics), timing, and account tiers. Nothing important is left unexplained for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds substantial semantic value: it explains depth's facet counts ('quick=3', 'standard=3 default', 'thorough=6'), the gap-recovery hop behavior, contradictions[] for standard/thorough, and that question accepts broad/multi-part natural language because decomposition is built-in. This goes well 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 specific verbs ('research', 'decomposes', 'routes', 'returns') and clearly identifies the resource ('Pipeworx's 1462 STRUCTURED data sources' via 5,564 tools). It explicitly contrasts with sibling tools by naming ask_pipeworx for single lookups and live news, making the purpose 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 'when to use' guidance: 'Best for broad/multi-part questions' with examples, and explicit 'when not to use': 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also states the account prerequisite and directs unauthenticated users to ask_pipeworx, covering alternatives clearly.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds key behavioral context: it returns tool metadata (names, descriptions, full input schemas) rather than actual data, and each result is 'ready to call directly, no second schema lookup needed'. This goes beyond annotations by explaining the output nature, though it omits details like ranking criteria or error 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 appropriately sized for a meta-tool. It front-loads 'Find tools by describing the data or task', then provides a relevant domain list, return-behavior details, and strategic usage advice. Every sentence contributes value, and the list of domains is useful, not padding. Structure is clear and scannable.

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

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

Despite having no output schema, the description fully explains what the tool returns: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)'. It also covers the default/max limit via the 'limit' parameter in schema. Given the tool's meta-purpose, the description is complete: it tells the agent what this discovery tool returns and when to invoke it.

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

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

Schema description coverage is 100% – all 6 parameters (query, q, task, search, description, limit) are described with aliases and examples. The description text reinforces that the query is a natural-language description, but adds no additional semantic information beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description opens with 'Find tools by describing the data or task' – a clear verb+resource+method. It explicitly lists the domains covered (SEC filings, FDA, FRED, etc.) and distinguishes itself from siblings as the discovery/meta-tool. The phrase 'Call this FIRST...' further separates it from domain-specific tools.

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

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

Provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist...' and strategic instruction 'Call this FIRST when you have many tools available...'. This is strong usage direction, clarifying when to use discovery vs. directly calling a specific tool.

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

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

Beyond annotations, it discloses the patents API sunset (May 2025) and soft-fail behavior, and notes that names are not supported. It also lists all return components and source APIs, providing rich behavioral context without contradicting the readOnly/idempotent annotations.

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

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

It is a single dense paragraph but efficiently packed with examples, output details, and constraints. Every sentence carries information, though it could be broken into shorter sentences for easier scanning. Still, it is not padded.

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 fully enumerates the return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and mentions source APIs and failure modes. This is comprehensive for a tool of this complexity.

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

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

The schema already has 100% coverage with descriptions for both parameters. The description adds concrete examples (ticker "AAPL", zero-padded CIK "0000320193") and reinforces the constraint that names are not supported, which slightly enhances the schema's static information.

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

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

The description states a specific verb and resource: "full cross-source profile of a US public company in ONE parallel call". It clearly distinguishes from siblings by advising "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups" and mentions resolve_entity for name-only inputs.

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

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

Explicitly tells when to use: when the user asks for a holistic view ("Tell me about X", "research Acme", etc.). It also gives an exclusion: "names not supported (use resolve_entity first)", and hints at alternatives like deep_research for broader queries.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description does not need to restate them. It adds useful context by specifying what gets deleted (previously stored memories) and a real-world scenario (clearing sensitive data). No contradiction with annotations.

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

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

The description is two sentences, front-loaded with the primary action, and provides usage context without any wasteful words. Every sentence earns its place.

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

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

This is a simple one-parameter tool with strong annotations and schema coverage. The description covers purpose, usage scenarios, and related tools, making it adequately complete for an AI agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, with the key parameter described as 'Memory key to delete.' The description reiterates 'by key' but adds no additional semantic detail beyond the schema, 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 'Delete a previously stored memory by key,' which is a specific verb (delete), resource (memory), and method (by key). This clearly distinguishes it from sibling tools remember and recall, making its purpose unambiguous.

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

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

It provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with remember and recall, but lacks explicit when-not-to-use guidance, so it falls just short of a 5.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses the operational pipeline: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies the output as a single text blob for site-root placement. No contradiction with annotations exists.

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

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

The description is three sentences, front-loaded with the primary action. Every sentence earns its place: main function, process, output, and use cases. No redundant or vague wording.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose, process, output format, and use cases adequately. Minor omissions like URL accessibility or error handling are not critical 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 provides full descriptions for both parameters (100% coverage), so the baseline is 3. The description adds no extra parameter-specific detail beyond what the schema already states, though it does mention extracting title/description/key links, which indirectly relates to how the url is used.

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 the exact action: 'Generate a production-ready llms.txt file for any URL' and explains its purpose for AI crawlers. This specific verb+resource clearly distinguishes it from sibling tools like ai_visibility_check, which focus on checking visibility rather than generating the file.

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

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

The description provides a clear 'Useful for:' section listing three specific use cases (client site indexing, self-project drafting, competitor auditing). It gives strong context on when to use the tool, though it does not explicitly mention alternatives or when not to use it.

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

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

Annotations already cover the read-only, idempotent, non-destructive nature. The description adds context about the caller-scoped list and the return fields, but does not disclose additional behavioral traits like pagination or permission requirements. This is adequate but not rich.

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

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

Two sentences, front-loaded with the primary purpose and return fields, followed by practical use cases. Every sentence contributes value, with no redundancy or fluff.

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

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

For a simple read-only list tool with no output schema, the description is complete: it states what it does, what it returns, and when to use it. The sibling context reinforces its role relative to subscribe/unsubscribe, and annotations cover safety.

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 optional parameter. The description's mention of 'active subscriptions' aligns with the schema's default for include_inactive, but does not add meaningful detail beyond what the schema already provides. 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 lists the caller's active subscriptions, a specific resource, and enumerates the returned fields. It distinguishes itself from siblings like subscribe and unsubscribe by focusing on listing rather than creating 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 provides explicit use cases: review monitoring before adding more subscriptions or find an id to cancel. It implies the alternatives (subscribe/unsubscribe) but does not directly name them or give when-not-to-use conditions, so it falls short of a perfect score.

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

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

The description goes well beyond the annotations (all false) by disclosing behavior: filing returns a claim_token, how to later query resolution status, a rate limit of 5 per identifier per day, and that it doesn't count against quota. It also notes the team reads digests daily and that signal affects roadmap. This is rich, useful context with no annotation contradiction.

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

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

The description is dense but every sentence carries a distinct purpose: purpose, when to use, exclusion, content guidance, claim-token workflow, and rate limit. It is front-loaded and structured, though the middle section is a bit long with multiple clauses. 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?

With no output schema, the description fully covers return behavior (claim_token and its later use), rate limits, and scope boundaries. It also handles the nested context object by telling users what to include (tool/pack/vertical) and provides type-enum guidance. The tool is a simple feedback form, and this description is complete.

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

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

Input schema coverage is 100% (baseline 3), but the description adds meaning: it explains the claim_token round-trip ('pass it back later as pipeworx_feedback({claim_token:...}) to read whether it was fixed'), and instructs users to describe issues in terms of Pipeworx tools/packs, not the end-user prompt. These details enrich the schema's bare parameter definitions.

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

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

The description opens with a clear, specific verb-resource pair: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates the exact feedback categories (bug, feature/data_gap, praise) and is clearly distinct from siblings like ask_pipeworx or discover_tools, which serve different functions.

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 'Use when' conditions list every feedback type: wrong/stale data (bug), tool missing from catalog (feature/data_gap), and positive experience (praise). It also gives a strong exclusion: if the tool came from a different MCP server, file it there instead. This makes it unambiguous when to invoke this tool and when not to.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context beyond annotations: it discloses the data source (CF analytics-engine), privacy implications ('no PII'), output granularity ('just (pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). No contradictions.

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

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

The description is concise yet complete: a one-sentence hook, a summary of outputs, three bulleted use cases, and two sentences on data provenance/caching. Every sentence adds unique value, and the structure is front-loaded with the core function.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is remarkably complete. It explains the return contents (top tools, packs, call volume), data origin, privacy characteristics, caching, and provides concrete usage scenarios—leaving no significant gaps.

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

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

Schema description coverage is 100%, including the enum values and their semantic tradeoff ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The description adds extra parameter-related context by linking window choice to cache freshness ('Cached 5min-1h depending on window'), going 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 clearly states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window.' It also specifies the resource (Pipeworx) and provides concrete use cases, distinguishing it from sibling tools like discover_tools or ask_pipeworx by focusing on aggregate usage trends.

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

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

The description explicitly lists three 'Useful for' scenarios, giving clear guidance on when to invoke the tool. However, it does not explicitly mention alternatives or exclusions (e.g., when to use discover_tools instead), so it stops short of the full when/when-not/alternatives guidance.

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

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

The description discloses extensive behavioral details beyond the annotations: the threshold for signals (deviations >3pp), the semantic anchor (Jaccard ≥0.30), the partition filter (placeholder slugs, >20% fraction), and the fill check using live CLOB depth. It also warns that 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade... do not trade it.' This adds transparency well beyond readOnly/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 with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. While it is long, every sentence provides necessary context for a complex tool. There is no redundancy; it efficiently packs mode explanations, examples, and edge-case behaviors into a cohesive block.

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 fully explains the response structure: opportunities[] with fields, partition_check object, and fill check details. It also covers default behavior (no args), edge cases (low similarity, placeholder filters), and actionable guidance (don't trade if realizable edge ≤ 0). 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?

Though the schema fully covers both parameters, the description adds significant semantic value: examples of slugs and seed questions, behavior for each parameter, and the no-arg default. It explains what the tool does with the 'event' and 'topic' values, including walking child markets, checking ordering, and running partition checks. This goes far beyond the schema's brief descriptions.

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

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

The description clearly states the tool's function: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the resource (Polymarket arbitrage), the action (find), and the method (monotonicity/partition-sum checks). It also differentiates from sibling tools by explicitly referencing polymarket_fill_risk for sizing.

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

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

The description provides explicit usage guidance for each mode: no-arg for trending_scan, 'event' for single-market scan with slugs, and 'topic' for cross-event scanning. It recommends 'event' for a specific market and explains when each is appropriate. It also points to polymarket_fill_risk for custom sizing, effectively distinguishing from an alternative.

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

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

Going well beyond the readOnly/idempotent annotations, the description discloses substantial behavioral details: caching at the KV level for 1 hour keyed on knobs, why Fed bets are excluded from ranking (unreliable signal), the gate relaxation for concentrated_longshot from prior runs, and the design quirk that partition arbs always return kelly_fraction_half=0 at the parent level. It also warns that a 24h move may already price in the edge. This is a rich, transparent behavioral account.

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 highly structured: it breaks the content into model families, opportunity components, response segments, and knobs. Every section serves a purpose for understanding the tool's behavior and output. It is dense but not wasteful; given the tool's complexity, the length is justified. A perfect score would require slightly tighter prose without sacrificing detail.

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

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

This is a complex tool with no output schema, so the description carries the full burden of explaining return values. It does so thoroughly: it lists the three segments under by_segment, the fed_candidates/fed_note exclusion, and the _diagnostics with funnel counters to explain empty segments. It also enumerates the fields carried by every opportunity (edge_pp_net, kelly_fraction, liquidity, etc.). Nothing critical is missing.

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

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

The input schema has 100% parameter coverage, so the baseline is 3. The description does add some context by labeling min_liquidity/max_spread_pp as 'TRADEABLE-EDGE KNOBS' and explaining how min_partition_leg_kelly interacts with partitions, but this largely repeats what the schema already states. The added value is minor, not enough to push above baseline.

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

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

The description opens with a specific verb+resource+goal: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes this tool from siblings like polymarket_arbitrage or polymarket_edge_tracker by detailing the model families and response segments. The purpose is unambiguous and directly actionable for an agent.

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

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

The description provides clear usage context: it is 'Built for "what should I bet on today"' and helps agents 'discover opportunities without paging hundreds of markets.' It explains the tradeable-edge knobs (min_liquidity, max_spread_pp) and when to adjust them, but does not explicitly name alternative tools or state when not to use this one. No exclusions are given, so it earns a 4 rather than a 5.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds substantial behavioral detail: data source from daily snapshots, response structure, snapshot gap semantics, and the nuance that edge_pp_net is signed by trade direction. It also clarifies that decay numbers come from daily closes, not intraday, and explains TTL bounds—all 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 organized into Args, RESPONSE, and LIMITS sections, front-loaded with purpose. It is dense but every sentence adds operational value, such as the interpretation of median lifespan as a competition clock and the note about snapshot gaps. Slightly long, but justified by the complexity.

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

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

With no output schema, the description fully specifies the response shape: tracked[], expired[], snapshot_dates[], including field-level semantics (trend values, decay_pp_per_day, lifespan_days). It also covers edge cases like snapshot gaps and data history bounds, making it highly 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?

The input schema already documents both parameters with descriptions, defaults, and clamps (100% coverage). The tool description only restates the default values ('default 14, max 30' and 'default "1wk"') without adding new semantic meaning or context, so it remains at the baseline.

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

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

The description clearly states its function: 'Edge persistence and decay telemetry' and the exact question it answers ('how long has this edge existed and is it shrinking?'). This distinguishes it from sibling tools like polymarket_edges, which presumably provides current edge data, by focusing on historical persistence and decay.

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 establishes a clear use case ('Answers ... is it shrinking?') and provides practical limits (60-day TTL, snapshot gaps). It does not explicitly name alternatives or when-not-to-use, but the context is sufficient for an agent to infer when to select this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds deep behavioral context: it walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, verdict), interprets size_usd differently by mode, and warns about partial-fill risk converting an arb into an unhedged position. No contradictions with annotations.

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

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

The description is long but well-structured: it opens with the core purpose, then breaks into SINGLE-MARKET and BASKET sections with clear parameter mappings and output lists. Every sentence adds useful information, though it could benefit from bullet points. It's appropriately detailed for a complex tool.

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

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

Given no output schema and 4 params with no required ones, the description fully compensates: it enumerates return fields for both modes, explains the verdict values, identifies risky legs, and provides context on when theoretical edge is not capturable. It's complete enough for an agent to understand tool behavior and output before 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 description coverage is 100%, so baseline is 3. The description goes beyond schema by explaining how size_usd maps to 'max spend on buys, target proceeds on sells' and basket 'settlement notional S (shares per leg; each share pays $1)', plus clarifies automatic side detection in basket mode. These are semantic clarifications the schema alone doesn't fully convey.

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 leads with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by explaining it's a pre-trade risk check for those signals.

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: '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) and describes two modes (single-market vs basket), which helps the agent choose between them.

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 readOnlyHint and idempotentHint annotations, the description richly discloses behavioral details: compatibility_warning conditions, skipped_cross_type/subtype counters, temporal_alignment semantics, and the warning that most pre-mapped topics return warnings. This adds substantial 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 long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and no filler. Every sentence carries useful information, though the length approaches the upper limit before conciseness suffers.

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 comprehensively explains the return shape: leg-by-leg prices, spread top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. It covers edge cases and the tool's complex matching logic, 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?

Although the schema already provides 100% parameter coverage, the description elevates understanding by explaining how 'topic' maps to ten shortcuts, how kalshi_event_ticker and polymarket_event_slug override the mapped side, and giving concrete examples. It clarifies the interaction between parameters and modes beyond the schema.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question', clearly identifying the tool's purpose and scope. It distinguishes from likely siblings like polymarket_arbitrage by focusing on cross-venue comparison rather than intra-venue analysis.

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 explains TWO MODES (topic shortcuts vs explicit ticker/slug) and provides when-not-to-use guidance via compatibility_warning and temporal_alignment. It does not name alternative tools, but the usage context is clear and includes strong caveats about pre-mapped topics not being tradeable.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds important behavioral context beyond these: the conditional dual-mode behavior (retrieve vs. list when key is omitted) and the scoping mechanism ('Scoped to your identifier'). This supplements the annotations without contradicting them.

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

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

The description is three sentences, each serving a distinct purpose: defining the operation, giving the usage context, and explaining scoping. It is front-loaded with the core action and avoids fluff or redundancy. No sentence is wasted.

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

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

Despite having no output schema, the description adequately covers the tool's behavior, scoping, and relationship to siblings. It explains both modes (retrieve by key, list by omission) and provides sufficient context for an agent to correctly select and invoke the tool. The tool is simple, and the description leaves no critical gaps.

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

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

The input schema provides 100% coverage of the 'key' parameter, including its optionality and the list-all behavior when omitted. The description adds value by giving real-world examples of what keys might contain ('the user's target ticker, an address, prior research notes') and clarifying that the value was 'previously saved via remember,' which enriches the semantics beyond the schema's mechanical definition.

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

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

The description clearly states both functions: retrieving a saved value by key and listing all keys when the key is omitted. It uses specific verbs ('retrieve', 'list') and explicitly ties the tool to its sibling tools ('remember' and 'forget'), distinguishing it from other tools in the list.

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

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

The description explicitly states when to use the tool: 'Use to look up context the agent stored earlier' with concrete examples (target ticker, address, research notes). It also implicitly contrasts with 'remember' (save) and 'forget' (delete) by saying 'Pair with remember to save, forget to delete,' giving clear guidance on alternative tools for different operations.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds useful behavioral details beyond that: the mark_read flag's side effect on future calls ('so the next call only shows newer ones') and the return payload composition ('each carries source, citation_uri, and the raw event payload'). It does not contradict any annotation and provides meaningful 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 three sentences long and front-loads the core purpose. Every sentence adds value: purpose, return format/filter/mark_read behavior, and polling/alternative endpoint note. 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?

With no output schema, the description compensates by explaining the return payload at a high level. It covers usage patterns (filters, mark_read), polling suitability, and an external reference for integration. The tool is simple and the description is complete for the given context.

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

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

The input schema already documents all 5 parameters with 100% coverage, so the baseline is 3. The description adds value by giving a concrete filter example ('e.g. "sec_8k"'), clarifying the 'since' parameter as an ISO timestamp, and explaining the consequence of mark_read in operational terms. This goes slightly beyond the repetitive schema descriptions.

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

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

The description uses a specific verb+resource construction ('Pull fired events from your subscription feed') and clearly identifies the tool's output ('Returns the most recent alerts the evaluator has written to your persisted feed'). It distinguishes itself from siblings like 'recent_changes' by explicitly focusing on alert events from the subscription feed.

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

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

The description gives clear context that this tool is suitable for polling ('Polls work fine') and provides an explicit alternative for scripts/dashboards via a direct HTTP endpoint ('the same feed is also at GET registry.pipeworx.io/alerts.json'). It does not explicitly state when not to use the tool, but the context is sufficient.

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 readOnly/idempotent/not-destructive annotations by disclosing data source fan-out (SEC EDGAR, GDELT→GNews fallback, USPTO), specific fallback conditions (rate-limited or 5xx), and the USPTO PatentsView sunset causing soft-fail. It also describes the return structure (changes[] grouped by source, total_changes, citation URIs), adding valuable behavioral context.

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

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

The description is dense but information-dense; every sentence contributes meaning, including source behavior, fallbacks, parameter syntax, and return format. It is slightly longer than ideal but appropriate for a multi-source aggregator with important caveats.

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, grouped sources, count, and citation URIs. It also covers parameter formats, source fallbacks, and a clear alternative, making it complete enough for correct selection and invocation.

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

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

Input schema already covers all parameters with 100% description coverage, so the baseline is 3. The description adds minor clarifications like 'Use 30d or 1m for typical monitoring' and ticker/CIK examples, but these mostly restate schema info rather than introduce new semantics.

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

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

The description clearly states the tool is a 'change feed for a company' covering filings, news, and patents, with example queries ('What's new with X', 'updates on Acme'). It distinguishes itself from sibling entity_profile by explicitly directing users to that tool for static profiles.

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

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

It provides explicit when-to-use contexts through natural language examples and names an alternative ('Use entity_profile instead when you want the static profile... regardless of window'). This gives clear guidance for selecting between recent_changes and related 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 already declare idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description adds valuable context beyond these: memory is scoped by the agent's identifier, authenticated users get persistent memory, and anonymous sessions retain data for 24 hours. This is useful behavioral disclosure, though it doesn't explicitly mention overwrite semantics for duplicate keys, which is a minor gap given 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 concise yet information-dense, front-loading the main action ('Save data the agent will need to reuse later') and following with specific use cases, storage mechanics, persistence rules, and sibling tool pairings. Every sentence earns its place, with no redundant filler or repetition of the title.

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

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

For a simple write tool with two string parameters and no output schema, the description is remarkably complete. It covers the tool's purpose, when to use it, storage semantics (key-value, scoped), persistence behavior (auth vs. anonymous), and how it relates to recall and forget. Nothing essential is missing for an agent to successfully select and 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 parameters with clear descriptions, so the baseline is 3. The description adds no additional parameter-level semantics beyond what the schema already provides—both 'key' and 'value' are fully explained with examples in the schema, and the description's examples (ticker, address, preferences) mirror those in the schema without adding new format or constraint information.

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

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

The description clearly states the tool saves data for later reuse, using the specific verb 'Save' and resource 'key-value pair'. It explicitly distinguishes itself from sibling tools by naming 'recall' for retrieval and 'forget' for deletion, making its unique role in the memory trio unambiguous.

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

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

The description provides explicit usage guidance: 'Use when you discover something worth carrying forward' and lists concrete examples (resolved ticker, target address, user preference, research subject). It also clarifies when to use alternatives by instructing to pair with 'recall' to retrieve and 'forget' to delete, establishing a clear decision framework.

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

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

Annotations already mark the tool as readOnlyHint=true and destructiveHint=false, but the description adds valuable behavioral details: internal cascading through multiple lookups, graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), and output structure (unresolved identifiers are explicitly stated rather than omitted). No contradictions with annotations.

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

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

The description is a single paragraph that front-loads with user-question examples and ends with a performance note. Though moderately long (≈150 words), every sentence adds value—explaining supported types, resolution behavior, and fallback logic. Could be slightly tighter without parenthetical asides, but efficient overall.

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 adequately explains the return semantics: identifiers labelled by source and a separate 'unresolved' field for failed lookups. It covers both entity types and edge cases (ISIN, graceful degradation). Missing a full structure listing, but sufficient for an agent to understand the output shape.

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

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

Schema coverage is 100% with descriptions for both parameters, so baseline is 3. The description adds meaningful enrichment: explains that the value parameter accepts ticker, CIK, ISIN, or company name, and details ISIN-to-LEI mapping for non-US issuers. This goes beyond the schema's brief 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 ('What's the ticker for…') then states precisely 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It lists supported entity types (company, drug) with detailed resolution logic, clearly distinguishing this lookup tool from sibling tools like compare_entities or entity_profile.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID,' providing clear usage priority. While it doesn't enumerate when NOT to use (e.g., if IDs are already known), the 'first' directive strongly implies the proper context. Alternatives like entity_profile are not mentioned, but the guidance is actionable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: pagination, per-field filtering, field projection, sorting, and the exact format/location of resourceId. It stops short of covering error handling or response format, but the annotation coverage lowers the burden.

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

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

Five sentences, all front-loaded with the core action. No filler; the example resource and field list earn their place. The structure moves from general capability to specific resourceId guidance to an actionable pointer to resource_meta.

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 7 parameters, nested objects, and no output schema, the description covers purpose, capabilities, example usage, and relationship to a sibling tool. It does not explicitly describe the return format, but the read-only annotations and 'fetch records' phrasing make the intent clear. Overall, highly complete for a data-fetching tool.

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

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

Schema description coverage is 100% for all 7 parameters, so baseline is 3. The description goes beyond by providing a concrete example resourceId and listing its fields (state, district, market, commodity, etc.), which helps the agent understand possible filter/sort values. It also directs to resource_meta for field discovery.

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: 'Fetch records from any India Open Government Data (data.gov.in) resource by its resourceId.' It clearly distinguishes this tool from siblings like resource_meta by focusing on record retrieval, not metadata.

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

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

It explicitly instructs when to use an alternative: 'Use resource_meta first if you do not know a resource's field ids.' This gives a clear precondition and names the sibling tool, providing both when-to-use and when-to-defer 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 cover safety (readOnlyHint, idempotentHint, non-destructive). The description adds behavioral context beyond annotations by specifying the return contents (metadata fields, field name/id/type) and the purpose of the resourceId. It does not contradict annotations.

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

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

Two sentences, leading with the action and resource, then providing the key use case. No filler or redundant content; every sentence earns its place.

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

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

Given the tool's simplicity, the description fully explains the return structure (title, org, sector, last-updated, field list with name/id/type) and its purpose. Missing details like error handling or rate limits are minor for a read-only metadata fetch, especially with strong annotations.

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

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

Schema covers 100% of parameters with descriptions and examples, so the baseline is 3. The description reinforces that resourceId is a UUID from the dataset page, which adds slight context, but no new parameter semantics 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's function: 'Fetch the schema/metadata for a data.gov.in resource by resourceId'. It lists the specific contents (title, org, sector, last-updated, fields), and explicitly distinguishes it from the sibling tool resource_data by saying 'before calling resource_data'.

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

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

Provides direct usage guidance: 'Use this to discover the filterable/sortable field ids before calling resource_data.' This tells the agent when to use this tool and how it relates to the likely alternative (resource_data), including the sequential dependency.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds value by explaining the probe-and-rank behavior and the return structure (ranked list with score, confidence, signal density). No annotation contradiction.

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

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

Two sentences, front-loaded with purpose, then use case, then output summary. Every sentence earns its place with zero waste.

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 summarizes the return format. Parameters are fully documented in schema, annotations cover safety, and the behavioral flow is clear. For a read-only, idempotent tool, this is complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics beyond schema, notably that the first entity is treated as the 'subject' and the rest as competitors, and that models are probed. This clarifies the role of the entities array.

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: 'Compare AI visibility across multiple entities side-by-side'. It also distinguishes from siblings by noting it probes with ai_visibility_check and ranks results, making it distinct from the single-entity ai_visibility_check and generic compare_entities.

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

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

Provides a concrete use case: 'competitive AI-marketing audits' with an example question. It implies when to use it (multi-entity comparison) but does not explicitly say when not to use alternatives. The reference to probing with ai_visibility_check implicitly contrasts with that sibling tool.

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

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

Annotations already mark readOnlyHint=true and idempotentHint=true, and the description adds behavioral context about graceful degradation ('Partial failures degrade gracefully'), potential latency ('bundlephobia's first measurement on a new version can take 5-30s'), and how failures are reported ('sources_failed will list it if it times out'). This exceeds the safety profile given by annotations.

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

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

The description is dense but well-organized, front-loading the core purpose in the first sentence, then providing usage, output, and failure info without redundancy. Each sentence adds new, actionable information for the agent.

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

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

Given the tool's composite nature and lack of an output schema, the description fully accounts for return values (summary block fields, per-advisory detail, links, alternative versions), ecosystem limitations, and failure modes. No critical context appears missing.

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

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

Schema already documents both parameters with 100% coverage, including scoped package support and default version behavior. The description does not add additional parameter-level detail beyond restating what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly identifies it as a composite check for deciding whether to add an npm package, listing both data sources (deps.dev, bundlephobia) and output fields. This distinguishes it from sibling research tools by its specific npm/package scope and composite nature.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides when-not-to-use and alternative: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly', giving clear exclusion criteria.

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

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

The description discloses rich behavioral details beyond the annotations: returns top-N passages with character offsets and similarity scores, enables quote verification, uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, and enforces a 200K-char cap with truncation flagged. This far exceeds the minimal readOnly/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 four sentences, each dense with purpose: the first defines the core action, the second specifies use cases and output, the third names a sibling integration, and the fourth gives technical constraints. The most important information is front-loaded, and no sentence is wasted.

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

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

Despite not having an output schema, the description fully explains what the agent can expect (passages, offsets, similarity scores). It also covers input size limits, truncation behavior, and the embedding approach. For a tool with only three parameters, this is complete and self-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 the baseline is 3; however, the description adds meaning by explaining that 'text' is 'the text you already pulled' and gives concrete query examples ('supply-chain risk', 'drug interactions with warfarin'), helping the agent craft effective queries. It also clarifies that text is the source to search within, not a general input.

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

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

The description opens with 'Semantic search INSIDE a fetched record' — a specific verb and resource — and clearly distinguishes this from sibling tools by emphasizing that it operates on already-fetched text rather than the wider corpus. It also names a complementary tool (ask_pipeworx_grounded), reinforcing its unique role.

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

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

Explicit guidance is provided: 'Use when the record is too big to cram into the prompt' and it explains how this tool saves context. It also pairs with ask_pipeworx_grounded, giving a concrete alternative workflow and making the when-to-use vs. alternatives 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 annotations, it discloses auth requirements, phone verification steps, SMS rate cap (10/day), webhook HMAC signing, and auto-disable after 10 consecutive failures. This significantly enriches the agent's understanding of side effects and constraints.

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 logically structured: purpose → return → auth → types → delivery. Each clause adds essential information; length is justified by the tool's complexity.

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

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

For a complex subscription creation tool with no output schema, the description covers prerequisites, all type variations, delivery channels, limits, and return value. Sibling tools handle listing/unsubscribing, so no missing context.

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

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

While the schema already documents all parameters, the description adds practical examples (e.g., items:['5.02'] = officer change) and clarifies delivery-channel requirements (verified phone for SMS, webhook secret returned once). This goes beyond bare schema descriptions.

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

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

The description opens with a clear verb+resource: 'Create a proactive monitoring subscription to a live-data event stream,' and specifies the return value (new subscription id). It clearly distinguishes this from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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 states prerequisites (Pipeworx OAuth account), enumerates supported subscription types, and contrasts the always-on feed (pullable via recent_alerts) with optional email/SMS delivery, implying when subscription is needed vs. one-off pulls. It does not explicitly name alternative tools, but the context is sufficient.

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; description adds the return structure (category-bucketed examples with tool+argument shape) and the no-argument vs topic-focused behavior. This provides useful behavioral context beyond the annotations.

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

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

The description is detailed but well-structured: it starts with query phrasings, defines the tool's purpose, lists categories, and explains usage. Each sentence serves a purpose.

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

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

The tool has no output schema and 1 optional parameter. The description covers when to use, how to call (with/without topic), what it returns, and how it relates to meta-tools. This is sufficient for an agent to invoke correctly.

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

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

Schema description already covers the topic parameter values. The description adds examples ('finance', 'pharma', 'betting') and clarifies the effect of passing a topic (focus the spread), adding value.

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

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

The description clearly identifies the tool as the onboarding entry point, stating it returns category-bucketed example questions with exact tool + argument shape. It distinguishes from siblings by advising 'Use this FIRST' when the agent doesn't know what Pipeworx can do.

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 gives the when: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. It also indicates the optional topic parameter for focus. However, it doesn't mention explicit alternatives like discover_tools or when not to use it.

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

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

The description adds significant behavioral detail beyond annotations: ownership enforcement, deactivation (not deletion), and preservation of historical events accessible via recent_alerts. This aligns with destructiveHint=false and enriches the agent's understanding of side effects.

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

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

The description is concise, front-loaded with the core action, and uses two sentences to convey all necessary information without any filler. Every word earns its place.

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

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

For a simple one-parameter tool, the description covers the core action, side effects, and data consequences. It doesn't describe the return value or error cases, but given the simplicity and the absence of an output schema, this is not a significant gap.

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

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

The input schema already fully describes the only parameter ('id' as a uuid returned by subscribe) with 100% coverage. The description adds no additional parameter meaning, so the baseline of 3 applies.

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

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

The description clearly states the action ('Cancel a subscription by id') and identifies the resource (subscription). It distinguishes from siblings like subscribe and list_subscriptions by specifying the exact operation and ownership enforcement.

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

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

The description clearly implies when to use this tool (to cancel a subscription) and provides an important boundary (ownership enforced, only your own subscriptions). It doesn't explicitly describe alternatives or exclusions, but the context is clear enough.

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

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

Beyond the readOnly/idempotent annotations, the description discloses internal behavior: two-pipeline architecture, verbatim evidence, judgment step, verdict vocabulary, and the precise meaning of could_not_verify (verification_error) versus unsupported. This is rich behavioral context that annotations alone do not provide.

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

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

The description is front-loaded with trigger phrases and usage, then flows into pipeline specifics, return values, and critical caveats. Every sentence adds operational value; it is detailed but not redundant, appropriately sized for a complex tool that replaces multiple steps.

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

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

Given no output schema, the description thoroughly covers return values (verdicts, actual value, citation, reasoning) and error semantics (could_not_verify vs. unsupported). It also covers both pipeline paths and the tolerance parameter, making it complete for an AI agent to invoke correctly in a wide range of claim-checking scenarios.

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

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

Although schema coverage is 100%, the description adds meaningful semantics: it explains how tolerance_pct interacts with the 'percent-delta math' and recommends 1–2 for hallucination detection, which goes beyond the schema's dry definition. It also clarifies the expected natural-language format for claim with examples.

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

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

The description clearly identifies the tool as natural-language claim verification against authoritative sources, with explicit trigger phrases and a specific verb-resource pairing ('validate claim'). It distinguishes itself from sibling tools by stating it replaces 4–6 sequential calls and by detailing two distinct verification pipelines (structured SEC EDGAR vs. grounded), making its 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?

It gives direct usage guidance ('Use whenever the agent needs to check whether something a user said is factually correct') and explains the routing logic for financial vs. other claims. It also provides important exclusion semantics for could_not_verify, telling callers not to treat it as evidence, which is practical when-to-use advice.

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