Sarb Za

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds important behavioral context: return format (per-model {score, confidence, signals, raw_response} + combined view), cost model (free for Workers AI, pay for Anthropic), and the fact that Anthropic requires a separate API key. No contradiction with annotations.

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

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

The description is a single, well-structured paragraph of four sentences. It front-loads the main action and output, then covers key details (default model, optional Anthropic, return format, 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 has 4 parameters, no output schema, and good annotations, the description fully covers what the tool does, what it returns (per-model details + combined view), usage contexts, and parameter nuances (default model, optional API key, disambiguation with context). No gaps.

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

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

Schema coverage is 100%, so all parameters are already described. The description adds some value by explaining the default model for 'models' parameter and clarifying that '_apiKey' is passed through to Anthropic. However, since the schema already covers parameter meanings, the description's additional contribution is marginal.

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 like 'probe' and 'score visibility (0-100) per model', clearly identifying the resource as LLMs and the output as visibility scores. It distinguishes from sibling tools by focusing on AI visibility auditing, which is unique among tools like 'ask_pipeworx' or 'deep_research'.

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

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

The description provides clear context for when to use the tool (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains the default model and optional Anthropic model with BYO key. However, it does not explicitly compare to similar sibling tools like 'scan_competitor_ai_presence' or provide when-not-to-use guidance.

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

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

Beyond the annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false), the description discloses additional behavior: it routes to tools, fills arguments, returns structured answers with citation URIs, works on every tier, and makes a single fast call. This gives the agent deeper insight into what the tool actually does.

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, front-loaded with 'PREFER OVER WEB SEARCH' and then systematically covering scope, routing, examples, and alternatives. Every sentence adds value; the length is justified given the tool's complexity and the amount of guidance needed.

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

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

With no output schema, the description explains the return format ('structured answer with stable pipeworx:// citation URIs'), covers the tool's scope, offers explicit comparisons to sibling tools, mentions performance characteristics ('one fast call'), and provides numerous examples. This is a complete picture for a complex tool.

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

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

Schema coverage is 100% and all parameters are aliases for 'question'. The description adds meaning with examples like 'current US unemployment rate' and 'Apple's latest 10-K,' and clarifies that natural-language queries are accepted. While the schema already documents the aliases, the description enriches the parameter's usage context.

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

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

The description clearly states the tool's purpose: 'Routes the question to the right one of 5,529 tools across 1,455 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It uses a specific verb ('ask') and resource ('Pipeworx'), and it distinguishes itself from sibling tools by naming alternatives like ask_pipeworx_grounded and deep_research.

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

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

Explicit when-to-use guidance is provided: 'PREFER OVER WEB SEARCH for questions about...', 'START HERE for most questions', and 'Step up only when needed: for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.' It also explains what to do for breaking news, making the usage boundaries very clear.

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

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

The description discloses behavioral traits beyond the annotations: it is a live experimental router with candidate improvements under test, currently inactive, and it falls back to nothing (it is a full working router). This adds important context about its changing behavior and comparison with the stable router, which annotations do not convey.

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

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

The description is well-structured and front-loaded with the essential identity ('Beta version of ask_pipeworx'). Every sentence earns its place, covering current state, usage, comparison, and fallback behavior without redundancy.

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

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

Given the tool's complexity as a universal router, the description is complete: it explains the relationship to ask_pipeworx, the experimental nature, current status, and response shape. No critical missing context for an agent to decide whether 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?

The input schema already documents all six parameters with 100% coverage, so the baseline is 3. The description adds no specific parameter semantics beyond stating 'same arguments' as ask_pipeworx, which is helpful but not detailed enough to raise the score.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,529 tools and arguments. It distinguishes from siblings by explicitly stating it is the experimental edge with candidate routing improvements, 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?

The description provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that it currently matches ask_pipeworx exactly and that results are compared against the stable router, giving clear context on when to prefer this variant over the stable 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?

Beyond the readOnlyHint, idempotentHint, and other annotations, the description discloses the exact return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and the explicit refusal reasons. It also reveals the one extra LLM call cost, which is a clear behavioral trait not captured in the annotations.

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

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

Although the description is somewhat long, every sentence contributes meaningful information: purpose, mechanism, return format, usage guidance, and cost trade-off. It is dense but efficiently structured, with 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?

Given the tool's complexity, the description covers the core routes, the refusal system, the use context, and the cost implication. There is no output schema, but the description provides the full return contract. It also acknowledges the scale (5,529 tools, 1455 sources) without overburdening the reader. The tool is fully contextualized for an agent.

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

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

The schema has 100% coverage with all parameters described as aliases for 'question' and the question parameter itself described as natural language. The description does not add further parameter-level semantics, which aligns with the baseline 3 for high schema coverage. No additional value beyond the schema is provided.

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

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

The description opens with a specific, action-oriented phrase: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly identifies the tool as a grounded variant of ask_pipeworx, explaining that it routes to the right tool, fetches data, and extracts answers only from the tool result. This distinguishes it from sibling tools like ask_pipeworx and validate_claim by emphasizing the refusal behavior and evidence extraction.

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

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

Explicit usage guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative (ask_pipeworx) and advises preferring that for casual lookups due to the extra LLM call. This fully covers when to use 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?

Adds extensive behavioral context beyond annotations: fan-out logic, response shapes, resolver contract, parent event extraction, safety mechanisms, closed market handling, wide spread warnings, and cancellation rule parsing. No contradiction with readOnly/ idempotent annotations.

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

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

The description is long but well-structured with clear sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). It front-loads the purpose and usage. Some redundancy exists, e.g., examples of fan-out are numerous, but each adds value.

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

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

Given complexity (3 params, no output schema), the description covers all aspects: purpose, usage, parameter details, response structure, error conditions (low-confidence, closed markets), resolution rules, and edge cases. It is sufficiently complete for an agent to correctly invoke and interpret results.

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

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

Schema coverage is 100% with clear descriptions. The description adds examples and context for the market parameter (slug, URL, question text) but does not significantly elaborate beyond schema. Depth and include_raw are well-covered in schema.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data in one call, specifying verb and resource. It distinguishes from sibling tools like polymarket_edges by detailing its comprehensive fan-out and evidence packet return.

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

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

Explicitly provides use cases (e.g., 'should I bet on X', 'is there edge in Z') and examples of when to use it. However, it does not explicitly mention when not to use it or directly compare to alternatives, but the context is clear.

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

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

The description adds significant behavioral context beyond annotations: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. All annotations are respected and complemented.

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 thorough and front-loaded with key information, but it is somewhat lengthy. However, every sentence serves a purpose, and the structure is logical, making it 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?

Given the tool's complexity and the presence of annotations and full schema coverage, the description covers purpose, usage, data sources, special logic, output format, and performance benefits. It is fully adequate without needing to mention rate limits or pagination.

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

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

With 100% schema coverage, the description adds substantial meaning: for the 'values' parameter, it provides examples (tickers/CIKs for company, drug names), constraints (2–5 items), and explains how data differs by type. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2–5 companies or drugs in a single parallel call, replacing multiple sequential lookups. It includes specific example queries and distinguishes from sequential single-pack lookups.

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

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

The description explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It explains when to use the tool and what data each entity type pulls, providing clear guidance without needing to exclude alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive; the description adds extensive behavioral context: account/paywall requirements, parallel routing, gaps[] never invented, contradictions scan, timing, semantic excerpting, and citation_uri fetchability. This goes far beyond what annotations convey 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 long but intentionally dense, with critical front-loaded info (account requirement and alternative). Every major behavior is covered, though there is slight redundancy between the 'findings packet' description and the later 'hop/citation_uri' details. Still, no wasted words 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?

For a complex tool with no output schema, the description fully compensates: it explains the findings packet, gaps[], contradictions[], citation behavior, execution time, prerequisites, and alternatives. An agent receives enough context to select and invoke the tool correctly across a wide range of cases.

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

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

Schema coverage is 100% for both params, but the description enriches them: it explains depth options (quick/standard/thorough), the default, the paid requirement for thorough, and the gap-recovery behavior. It also reinforces the question param's flexibility with 'Broad/multi-part is fine'. This is additive value beyond the schema.

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

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

The description states a specific verb+resource+scope: 'grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and 'Decomposes your question into focused facets'. It clearly distinguishes itself from open-web search and sibling tools like ask_pipeworx, making its niche 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?

Explicit when-to-use and when-not-to-use guidance is provided: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It names specific alternatives and exclusion conditions, which is excellent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that results are 'ready to call directly, no second schema lookup needed,' which is a behavioral trait beyond annotations. No contradiction.

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

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

The description is front-loaded with purpose and includes essential details. While slightly verbose, every sentence adds value (examples, usage guidance, return format). Could be slightly trimmed but still effective.

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

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

Given 6 parameters (mostly aliases) and no output schema, the description sufficiently explains what the tool does and what it returns (top-N tools with schemas). It provides examples and usage context, making it complete for an agent.

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

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

Schema coverage is 100% with descriptions for all 6 parameters. The description adds meaning by explaining the query parameter expects natural language and lists aliases. Examples in schema further clarify usage.

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

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

The description clearly states 'Find tools by describing the data or task.' It uses a specific verb-resource pair and distinguishes itself from siblings by focusing on browsing/searching for tools. It lists many example domains, 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?

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance. It also explains what the tool returns (top-N, ready-to-call tools), which helps the agent decide when to invoke 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds context about fanning out across multiple sources, return fields, and soft-fail behavior for patents, enhancing transparency beyond annotations.

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

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

Description is a single dense paragraph that packs much information efficiently. It is front-loaded with examples and summary, then details. Could be slightly improved with structural elements like bullet points, but remains clear and not wasteful.

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

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

For a tool with 2 params, no output schema, and high complexity (multiple sources), the description is thorough: it explains inputs, outputs, fallbacks, alternatives, and even future deprecations. Nothing essential is missing.

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

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

Schema coverage is 100% with clear property descriptions, but description adds significant value by explaining that value can be ticker or zero-padded CIK, and that names are not supported. Also clarifies type enum limitations.

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

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

Description clearly states the tool provides a holistic cross-source profile of US public companies in one call, listing sources and returned data. It distinguishes from siblings by explicitly stating it should be preferred over chaining individual lookups.

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

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

Explicitly advises to prefer this tool over chaining single-pack lookups, specifies input requirements (ticker or CIK, not names), and directs to resolve_entity for names. Also notes soft-fail for patents due to API sunset.

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, covering the destructive nature. The description adds context about deleting stored memories and clearing sensitive data, which aligns with annotations. No contradictions, but no further behavioral details beyond what annotations imply.

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

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

Four sentences, each purposeful. First sentence defines the action, second provides usage context, third suggests pairing. No fluff, front-loaded with the core purpose.

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

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

For a simple destructive tool with one parameter and no output schema, the description covers purpose, usage, and related tools. It does not explain success/error behavior, but that is inferable for a delete operation. Minor gap in return value documentation.

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

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

Schema coverage is 100% with parameter 'key' described as 'Memory key to delete.' The description says 'by key' but does not add new semantics or format constraints beyond the schema. 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?

Description explicitly states 'Delete a previously stored memory by key.' It uses a specific verb (Delete) and resource (memory by key). It distinguishes from siblings like 'remember' and 'recall' by clarifying the action is deletion.

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

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

Description provides clear guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also suggests pairing with 'remember' and 'recall,' offering alternative tools for related tasks.

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

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

The description explains the process ('Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format') and output format, adding value beyond annotations. It does not contradict annotations. Minor gap: doesn't mention potential variability due to live site changes.

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 with two main sentences and a bullet list, front-loading the purpose. No redundant information, though the bullet list could be integrated into the prose for slight improvement.

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

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

With only two parameters, no output schema, and clear annotations, the description sufficiently covers what the tool does, how it works, and use cases. It leaves no major gaps for an AI agent to invoke the tool incorrectly.

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

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

Schema description coverage is 100%, and the description essentially restates the schema for 'url' and 'max_links' without adding new semantic context. The default and max for max_links are already in the schema, so the description provides no additional benefit.

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 ('Generate'), the resource ('production-ready llms.txt file'), and the target ('any URL'). It distinguishes from siblings by specifying the exact purpose and output format, making it unambiguous.

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

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

The description lists specific use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), providing good context. However, it lacks explicit 'when not to use' or direct comparison to sibling tools like 'ai_visibility_check'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds value by listing return fields and default for include_inactive, but does not cover additional behavioral traits.

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 concise sentences. First sentence states purpose and return fields, second gives usage guidance. No unnecessary 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 one optional parameter, full schema coverage, annotations covering safety, and description specifying return fields, the definition is complete for a list tool.

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

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

Schema coverage is 100% and schema description for the single parameter is clear. Description does not add additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

Description clearly states the verb (list) and resource (subscriptions), and specifies the fields returned. It distinguishes from sibling tools like subscribe/unsubscribe.

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

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

Explicitly advises using this tool to review subscriptions before adding more or to find an ID to cancel, providing clear context for 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 are all false and provide no safety or behavioral hints, so the description carries full weight. It discloses the anonymous filing returns a claim_token, how to later check status, daily digest cadence, rate limit (5 per identifier per day), and that it doesn't count against quota. It also warns against pasting end-user prompts, adding context beyond what annotations/schema reveal.

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

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

The description is long but every sentence earns its place. It front-loads purpose, then systematically covers use cases, exclusions, formatting guidance, and post-filing mechanics. No redundant sentences or filler; the length is justified by the tool's dual submit/check 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?

Given the tool's complexity (two modes: submit feedback, check status), the description is fully complete. It covers use cases, scope boundaries, input expectations, return behavior (claim_token), rate limits, and roadmap impact. The absence of an output schema is compensated by explaining what the token returns and how to read status.

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

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

Schema already covers 100% of parameters with descriptions. The description adds operational nuance: passing claim_token alone ('with no other arguments') reads status, and message should describe issues in Pipeworx tool terms rather than pasting prompts. This elevates beyond schema but doesn't fully redefine semantics since type/context are already well-documented.

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

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

The first sentence clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates the feedback categories (bug, feature/data_gap, praise). No sibling tool serves this role, so it is unambiguously distinct.

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 triggers: returns wrong/stale data, missing tool, or positive praise. It also gives a strong exclusion: 'ONLY for tools served by this Pipeworx connection' and directs users to file with other MCP servers. Additional guidance on message format and claim_token follow-up fully covers usage.

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

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

Adds beyond annotations: explains aggregation source (CF analytics-engine), no PII, caching behavior. 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?

Four sentences, front-loaded purpose, no unnecessary 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?

Low complexity; no output schema but description adequately describes return content and caching. All needed info present.

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% with enum; description reinforces window meaning and adds context about hot vs steady-state demand.

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 returns top tools, top packs, and call volume over a window, distinguishing it from siblings like discover_tools or 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 lists three use cases and explains window selection trade-offs, but does not mention when not to use or alternative tools.

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

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

The description extensively covers behavioral traits beyond annotations: scanning top 200 markets, checking monotonicity, partition checks, Jaccard similarity for cross-event, placeholder filtering, fill check with CLOB depth, and trade recommendations. 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 well-structured, starting with the main purpose and then detailing each mode, filters, and response. However, it is somewhat verbose with technical details; could be more concise while retaining completeness.

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

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

Given the tool's complexity and lack of output schema, the description is highly complete. It covers all modes, edge cases, response format, fill check, and references another tool for custom sizing. No gaps identified.

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

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

Schema coverage is 100%, but the description adds significant value by providing examples, mode explanations, response structure, and behavioral nuances for both parameters. This far exceeds what the schema descriptions provide.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinctively describes three modes (no args, event, topic), each with specific use cases, differentiating itself well from siblings.

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

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

The description explicitly instructs when to use each argument: no args for trending scan, event for a specific market, topic for cross-event scanning. It provides examples and recommends event mode. However, it lacks explicit alternatives or when-not-to-use guidance relative to sibling 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 declare readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint false. The description adds substantial context beyond annotations: caching behavior ('Cached 1h at the KV level keyed on all knobs'), detailed response structure (by_segment, _diagnostics), and explanation of model families with specific methodologies (e.g., lognormal barrier from 90d FRED log-returns, GDELT article-volume ratio). No contradictions found.

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

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

The description is extremely detailed and informative but overly verbose, containing dense domain-specific jargon and inner workings (e.g., 'per-leg favorite-longshot bias correction with per-sport α (tennis 1.02, soccer 1.10, MMA 1.15, default 1.0)'). While well-structured with sections and parentheses, the length may hinder quick parsing by an AI agent. Some sentences are cluttered with technical specifics that could be summarized.

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 detailing the response structure: top-level by_segment, fed_candidates/fed_note, and _diagnostics with funnel counters. It explains fields like edge_pp_net, kelly_fraction, and 24h-move warning. Cache behavior, parameter interactions (e.g., min_liquidity with partition_overround), and edge cases (e.g., Fed bets excluded from ranking) are covered comprehensively. No gaps remain for an agent to invoke the tool correctly.

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

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

All 9 parameters have schema descriptions (100% coverage). The tool description adds value by explaining parameter intent and usage, e.g., for min_kelly: 'Skips opportunities that are too small to bet sensibly even if the edge is large.' For min_partition_leg_kelly, it clarifies its interaction with partition arbs. The only minor gap is that some parameter behaviors, like the default for category_filter, are implicit but not explicitly stated in the description.

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

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

The description explicitly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It provides a specific verb (scan/return), resource (Polymarket markets), and unique angle (disagreement detection). The extensive detail on three segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) differentiates it effectively from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 frames usage with 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It details tradeable-edge knobs (min_liquidity, max_spread_pp) and when to apply them, and explains filter parameters like min_kelly and min_edge_pp. However, it does not explicitly state when not to use this tool versus siblings like polymarket_arbitrage, nor does it provide alternative tools for related tasks.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description aligns fully. It adds details about response structure (tracked, expired, snapshot_dates) and limits (60-day TTL, daily close decay), going beyond annotations.

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

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

The description is logically structured with a purpose statement, response field details in a clear format, and limits. It is dense but each sentence contributes value. Slight length is justified by complexity.

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

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

Given the tool's complexity (time-series, multiple response arrays, limits) and absence of output schema, the description thoroughly explains output fields and constraints. It provides sufficient context for correct usage.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful context: explains 'days' as lookback with default 14 and max 30, and 'window' as snapshot family with examples. This exceeds 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 explicitly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It distinguishes from siblings like polymarket_edges by focusing on time-series and trend analysis, answering 'how long has this edge existed and is it shrinking?'.

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 on when to use the tool (to evaluate edge longevity and decay) and contrasts fresh vs. old edges. However, it does not explicitly state when to use alternatives or when not to use this tool, leaving some ambiguity for an AI agent.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description discloses return fields (top_of_book, vwap, slippage, verdict, etc.), mode-specific behavior (walking the ladder, capturing overround), and failure modes (thin_legs, forced_directional_risk). No contradiction with annotations.

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

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

The description is detailed but well-structured with clear sections (REQUIRES, SINGLE-MARKET:, BASKET:). Every sentence serves a purpose, but could be slightly more concise without losing clarity. Front-loaded with core purpose.

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

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

For a tool with 4 parameters and no output schema, the description covers all necessary aspects: parameter explanations, return values, use cases, warnings. It is comprehensive and leaves no obvious gaps for an AI agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra context: side options explained for both modes, size_usd interpretation (max spend vs target proceeds vs settlement notional), default values, and clamp range. This adds meaningful value beyond schema.

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

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

The description clearly states the tool's purpose as a realizable-vs-theoretical edge check against live order-book depth, with distinct modes for single-market and basket. It explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use this tool before acting on 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?

Detailed guidance is provided: when to use (before arb signals or trades above $500), mode selection (require market or event), side defaults, and behavior under partial fills. Risks of unhedged positions are clearly explained, enabling correct tool selection.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds extensive context: when spreads are meaningful (compatibility_warning, temporal_alignment), what response contains, and safety fields. No contradiction.

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

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

Description is long but packed with essential information for a complex tool. Front-loaded with main purpose, structured by modes and safety fields. Slightly verbose but all sentences add value.

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

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

Given complexity (3 params, no output schema), description covers all important aspects: modes, response, safety fields, edge cases. Lacks explicit response structure, but field descriptions compensate.

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. Description adds explicit topic values, examples, and explains interaction between topic and explicit tickers, adding meaning beyond the schema.

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

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

Clearly states it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from siblings like polymarket_arbitrage. Explains two modes (topic shortcuts and explicit tickers) with specific verb 'cross-venue spread'.

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 detailed guidance on when to use each mode and warns that most pre-mapped topics return compatibility_warning. Does not explicitly compare to alternative tools for similar tasks.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds context about scoping by identifier and the listing behavior, enhancing transparency without contradiction.

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

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

Two sentences, no wasted words, highly efficient while conveying all necessary information.

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

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

For a simple tool with one optional parameter and complete annotations, the description covers scoping, pairing with siblings, and basic behavior, making it fully adequate.

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

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

Schema coverage is 100%, but description adds meaning by explaining that omitting the key lists all keys, which goes beyond the schema description.

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

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

The description clearly states the tool retrieves a saved value or lists all keys, with specific verb+resource and distinguishes from sibling tools (remember, forget).

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 strong guidance on when to use (look up context without re-deriving) and scoping, but lacks explicit negative guidance on when not to use.

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

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

Annotations declare readOnlyHint=true, but description says mark_read:true flags events as read, implying state mutation. This contradicts the readOnlyHint annotation. No other behavioral traits disclosed.

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

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

Four sentences, front-loaded with purpose. Each sentence adds distinct value: purpose, return fields, filter options, side effect, and alternative access. No redundancy.

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

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

Covers all necessary aspects: what it does, parameters, optional side effect, alternative access, and polling suitability. No output schema needed given rich description and annotations.

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

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

Adds significant meaning beyond schema: explains 'type' with example 'sec_8k', 'since' as ISO timestamp, limit range 1-200 default 50, mark_read effect, and unread_only behavior (read_at null). Schema coverage is 100%, but description enriches with concrete examples and constraints.

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?

Clear verb-object pairing: 'Pull fired events from your subscription feed.' Specific and distinct from sibling tools like recall or recent_changes. Also provides details on returned fields (source, citation_uri, raw payload).

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?

States polls work fine and mentions an alternative endpoint for scripts/dashboards. Does not explicitly contrast with siblings but gives clear context for appropriate use.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral details: it fans out to SEC EDGAR, GDELT→GNews fallback (with explanation of when fallback occurs), and USPTO patents with a note about API sunset. It also describes the return structure with changes[], total_changes, and citations. 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 relatively long but front-loaded with example queries and a clear purpose statement. Every sentence provides useful information, such as source details, fallback behavior, and output format. It could be slightly more concise, but the structure effectively supports understanding.

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

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

The tool has no output schema, so the description must explain return values; it does: 'Returns structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs.' It also covers multi-source behavior, fallback, and date parsing. Given the complexity, this description is complete and 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?

Schema coverage is 100% so baseline is 3. The description adds value beyond schema: it explains that `since` accepts ISO date format or relative shorthand, gives examples, and recommends typical values. This clarifies usage 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 starts with clear example queries and states it is a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It explicitly distinguishes from the sibling tool entity_profile, saying when to use that instead. The purpose is specific, actionable, and clearly differentiated.

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

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

The description provides explicit guidance on when to use this tool versus entity_profile ('Use entity_profile instead when you want the static profile...'). It also advises on the `since` parameter with examples and recommendations ('Use "30d" or "1m" for typical monitoring'), fulfilling the when-to-use and parameter-usage 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?

Adds context beyond annotations: scoping by identifier, persistence differences (authenticated vs anonymous), and 24-hour retention. Idempotent and non-destructive nature is consistent with annotations.

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

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

Concise single paragraph, front-loaded with purpose, every sentence adds value. 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 simple 2-param schema and no output schema, the description fully explains behavior, usage, persistence, and relationships with sibling tools (recall, forget). No gaps for this tool's complexity.

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

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

Schema coverage is 100% with clear descriptions, so baseline is 3. The description adds examples and scoping context but does not significantly enhance parameter meaning beyond the schema.

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

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

The description uses a specific verb (save) and resource (data for reuse across conversation/sessions) and distinguishes from siblings by explicitly naming paired tools (recall, forget). Concrete examples (resolved ticker, target address) clarify scope.

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

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

Clearly states when to use: 'when you discover something worth carrying forward' and implies avoiding repeated lookups. Mentions paired tools for retrieval and deletion but lacks explicit when-not-to-use guidance.

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

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

Despite having rich annotations (readOnly, openWorld, idempotent, non-destructive), the description goes beyond them by disclosing important behaviors: unresolved identifiers are explicitly stated under `unresolved`, LEI/FIGI enrichment degrades gracefully if GLEIF/OpenFIGI is unavailable, and each call cascades through multiple internal endpoints. These details are not implied by the annotations and are highly useful for the agent. 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 well-structured and front-loaded with example queries that immediately convey usage. It uses a 'SUPPORTED TYPES' subsection to organize detailed information, and every sentence adds value—no fluff. Although it is longer than average, it is appropriately sized for the complexity of the tool.

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

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

Given that there is no output schema, the description thoroughly explains what the tool returns: labeled identifiers, unresolved identifiers under `unresolved`, citations for drug lookups, and fallback behavior. It covers failure modes and integration details, making the tool fully understandable without external documentation. This is complete for a tool with two parameters and no output schema.

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 covers both parameters (type and value) with descriptions, the description adds substantial meaning beyond the schema. It explains the exact input forms for 'value' per type (e.g., ticker, CIK, name for company; brand or generic for drug) and lists the specific identifiers returned (CIK, ticker, LEI, FIGI, RxCUI, etc.). This enriches the parameter semantics far beyond the schema definitions.

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

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

The description explicitly states the tool's purpose: resolving user-spoken names to canonical/official identifiers required by other tools. It uses a clear verb ('resolve') with a specific resource ('user-spoken NAME to identifiers'), and differentiates itself from siblings with 'Use FIRST whenever you have a name but need an ID.' The example queries further clarify the scope.

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

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

The description provides explicit guidance on when to use the tool: 'Use FIRST whenever you have a name but need an ID.' It also implies exclusions by stating what it does (resolves names to IDs) and explains that it replaces 2-3 manual lookups, giving context on its efficiency. This is clear usage direction with no ambiguity.

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

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

Description adds value beyond annotations by specifying return content (interest charged/earned, TimeseriesCode). No contradictions with annotations; all hints are consistent.

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, no filler, front-loads the purpose and key actionable details (TimeseriesCode). 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?

Coverage is good given low complexity and rich annotations. Could optionally include information about rate validity or typical usage context, but currently sufficient for selection and basic understanding.

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

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

Schema coverage is 100% and already documents the single parameter as ignored. Description adds 'No arguments' which is slightly inconsistent with the presence of the parameter but clarifies usage. Does not add significant semantic depth beyond schema.

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

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

Clearly identifies the tool as returning current CPD interest rates, both charged and earned. Mentions that each item includes a TimeseriesCode for use with the sibling `sarb_timeseries` tool, effectively distinguishing it from other SARB 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?

States 'No arguments' and describes relationship to `sarb_timeseries`, implying when to use that tool instead. However, lacks explicit when-not-to-use guidance or alternatives among siblings.

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

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

Annotations already cover readOnly, idempotent, and destructive hints. The description adds context about the specific rates returned and the link to another tool, which is valuable 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 two sentences, front-loaded with the core purpose. Every sentence adds value, and there is no extraneous 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?

Given the simplicity (0 parameters, no output schema), the description is sufficient. It tells what the tool returns and provides a usage hint. It could be more explicit about the output structure, but it is adequate for the agent.

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

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

The tool has zero parameters, and the description explicitly states 'No arguments,' meeting the baseline for parameterless tools. No additional semantic context is needed.

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

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

The description clearly states it returns current South African money-market rates and lists specific rates (SARB Policy Rate, Sabor, Zaronia). It also differentiates from sibling tools like sarb_exchange_rates and sarb_home_rates by the focus on money-market rates.

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 usage hint: the TimeseriesCode can be used with the sarb_timeseries tool. However, it does not explicitly exclude alternative tools or state when not to use this tool, but the naming and context are sufficient for most scenarios.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds that rates are 'latest' and monthly includes indices, plus hints at integration with sarb_timeseries, providing useful behavioral context beyond annotations.

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

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

Two concise sentences with no filler. First sentence states purpose, second explains the parameter effect. Front-loaded and efficient.

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

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

Despite no output schema, the description mentions TimeseriesCode and gives examples of currencies and indices. Some output structure details are missing, but overall it provides reasonable completeness for a simple data retrieval tool.

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

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

Schema coverage is 100% with enum values described. The description goes further by explaining what each frequency returns (daily: major currencies, monthly: indices), adding meaningful context for parameter selection.

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

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

The description clearly states it provides selected South African Rand exchange rates with specific frequency options. It distinguishes from sibling tools by mentioning TimeseriesCode usable with sarb_timeseries.

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 explains the two frequency options but does not explicitly state when to use this tool versus other Sarb tools like sarb_cpd_rates or sarb_current_market_rates. Usage context is implied but lacks direct guidance on alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as true/false. The description adds context on what data is returned (specific rates) and that the tool takes no arguments, aligning with annotations. No contradiction.

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

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

The description is a single concise paragraph that efficiently lists the data provided, mentions the TimeseriesCode link, and explicitly states the lack of arguments. No redundant information.

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

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

Given no output schema, the description provides a good overview of what the output contains (inflation rates, policy rate, exchange rates, etc.) and the TimeseriesCode. However, it could be slightly more explicit about the return format, though the tool's simplicity makes it 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?

There are zero parameters, so the description's statement 'No arguments' is sufficient. Baseline for 0 parameters is 4. Schema coverage is 100% trivially, and no additional parameter meaning is needed.

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 that the tool returns 'Current headline South African rates shown on the SARB home page' and lists specific rate categories (CPI, PPI, policy rate, etc.). This distinguishes it from sibling tools like sarb_exchange_rates which only returns exchange rates.

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

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

The description implies when to use the tool: to get current headline rates. It mentions that each item includes a TimeseriesCode for use with sarb_timeseries, suggesting a workflow. However, it does not explicitly state when not to use it or provide comparisons with siblings like sarb_current_market_rates.

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

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

Annotations indicate readOnly, idempotent, non-destructive. The description adds critical context: unknown codes return an empty list, date format (YYYY-MM-DD), and the relationship between start/end dates. This goes beyond annotations, though rate limits or data freshness are not mentioned.

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

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

The description is two sentences plus examples, front-loading purpose and usage. Every sentence adds value, with no redundancy. Examples are embedded naturally.

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 3 straightforward parameters, no output schema, and no nested objects, the description covers all essential aspects: what the tool does, how to get codes, date behavior, and error handling (empty list for unknown code). It is complete for an agent to use correctly.

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

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

Schema coverage is 100% with descriptions, but the schema's mutual requirement statements for start/end dates are ambiguous. The description clarifies that both are optional when used together, and provides concrete examples. This adds meaning beyond schema alone.

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

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

The description clearly states the tool retrieves historical observation series for a single SARB indicator by TimeseriesCode. It provides specific examples of codes, differentiating from sibling tools (which provide the codes) and making the purpose unambiguous.

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

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

The description advises obtaining codes from four sibling tools, which is excellent guidance. It explains optional date range parameters and the behavior when omitted. It could be improved by explicitly stating when not to use this tool, but the guidance 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds that it internally calls ai_visibility_check and returns a ranked list with score, confidence, and signal density. No contradictions. Could mention rate limits or API key dependency more explicitly, but schema covers the key.

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: first states core function, second adds use case and output details. No wasted words, front-loaded key info.

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

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

No output schema, but description covers return structure (ranked list with scores, confidence, signal density). Explains internal call to ai_visibility_check and optional _apiKey. Missing error scenarios or what happens on probe failure, but overall complete for a comparison tool.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning by noting that the first entity is treated as the 'subject' for narrative, providing context beyond the raw description. This adds value, hence a 4.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, and returns a ranked list. It distinguishes from the sibling ai_visibility_check by focusing on side-by-side comparison.

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 a concrete use case ('does Claude know about us as well as our competitors?') and implies when to use (competitive audits). It does not explicitly state when not to use but the context from siblings helps. Could mention alternatives like ai_visibility_check for single entities.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds behavioral traits: composite fan-out across two services, partial failures (bundlephobia timing 5-30s, sources_failed list), and graceful degradation. 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 long but every sentence adds value. It is well-structured: first sentence summarizes the tool, then usage, return structure, limitations, and alternatives. Front-loaded with the key 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?

Despite no output schema, the description thoroughly explains the return values (summary block, per-advisory detail, links, alternative versions). It also covers ecosystem limitations, timing issues, and fallback behavior, making the tool fully understandable.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The description adds context on how parameters are used in the composite call but does not provide new semantic details 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 as a composite check for adding npm packages, covering license, advisories, version history, bundle size, and more. It distinguishes itself from sibling tools like validate_claim or deep_research by its specific focus on npm dependency evaluation.

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: when an agent asks about safety, popularity, or size of an npm package. Also provides exclusions (non-npm ecosystems) and suggests an alternative: using deps.dev:version directly for PyPI/Maven/Cargo/Go.

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. Description adds return format (top-N passages with offsets and similarity scores), algorithm (BGE-base-en embeddings + cosine over 500-char windows), and cap (200K chars with truncation). No contradictions.

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

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

Three sentences, well-structured, front-loaded with key usage, no fluff. Every sentence adds value.

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

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

Given 3 parameters, no output schema, and rich annotations, the description covers algorithmic details, cap, offset feature, and pairing suggestion. Complete for the tool's purpose.

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 per-parameter descriptions. Description reinforces text and query parameters with examples and cap info, but adds marginal value beyond schema. Baseline 3 is appropriate.

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

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

The description clearly states it performs semantic search inside a fetched record, with specific examples (SEC 10-K, article) and contrasts with a sibling tool (ask_pipeworx_grounded). The verb 'search within' is specific and resource-oriented.

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 ('when the record is too big to cram into the prompt'), provides pairing guidance with ask_pipeworx_grounded, and mentions the 200K char cap with truncation flag. Full usage context.

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

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

Annotations already provide idempotent, non-read-only, non-destructive hints. The description adds rich behavioral context: OAuth requirement, type-specific parameters, delivery channel constraints (SMS cap, webhook auto-disable after 10 failures), and signing details. 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 comprehensive and front-loaded with the main purpose. While dense, every sentence adds value. Minor structure improvement possible (e.g., bullet lists), but overall efficient.

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

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

Given three parameters, nested objects, and no output schema, the description is thorough. It covers types, parameter formats, delivery options, and constraints. However, it could mention that the subscription ID is returned and that webhook secret is returned once. Still, very complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptive fields. The description goes further with concrete examples for each 'type' and detailed 'params' and 'delivery' objects, including constraints like phone verification and webhook HMAC. Adds significant meaning beyond schema.

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

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

Clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' Provides specific verb+resource and distinguishes from siblings like 'unsubscribe' and 'list_subscriptions'.

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 requires a 'Pipeworx OAuth account' and notes that anonymous/BYO cannot persist, providing clear context. Does not explicitly mention alternatives among siblings, but the conditions for use are well-stated.

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

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

Annotations already indicate read-only, idempotent, open world, non-destructive. Description adds valuable context: returns example questions with tool+argument shapes from a live catalog, and behavior for parameter omission. 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?

One dense sentence front-loads the core purpose and includes many aliases and use cases. Could be more concise or split into shorter sentences, but packs information efficiently.

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

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

Despite no output schema, the description clearly explains the return format: category-bucketed example questions with tool+argument shapes. For a simple one-parameter 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% with a description of the topic parameter. Description adds minimal extra value by listing possible values and behavior when omitted, but mostly restates schema info.

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 serves as an onboarding entry point, returning category-bucketed example questions with exact tool and argument shapes. It distinguishes itself from sibling tools like ask_pipeworx by being specifically for suggesting questions.

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

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

Explicitly says to use this FIRST when unfamiliar with Pipeworx or to learn meta-tools. Provides guidance on calling with no arguments for full spread or with a topic to focus. Lacks explicit exclusion scenarios but context is clear.

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

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

The description discloses key behavioral details beyond annotations: the row is deactivated (not deleted) and historical events remain available via recent_alerts. This adds significant transparency and aligns with the destructiveHint=false annotation.

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

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

Three concise sentences, each adding essential information: action, ownership constraint, and deactivation behavior. No extraneous words.

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

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

The description covers purpose, ownership enforcement, and side effects, but lacks information about the return value or success/error response. For a simple mutation tool, this is a minor gap.

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

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

With 100% schema coverage, the schema already documents the 'id' parameter as a UUID from subscribe. The description adds no additional semantic detail, meeting the baseline of 3.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource ('subscription'), distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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 an important usage constraint: ownership is enforced, so only own subscriptions can be cancelled. However, it does not explicitly mention when to use this tool versus alternatives or provide when-not-to guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds critical behavioral nuance: the meaning of could_not_verify (internal failure, not evidence) and unsupported (no source coverage). It also reveals internal routing logic (SEC fast path vs. grounded fallback), which goes beyond the annotation hints.

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

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

Although fairly long, every sentence adds useful information: example phrasings, when to use, internal routing, return value types, error semantics, and performance benefit. It is front-loaded with the most relevant information and avoids redundant filler. The structure is logical and well-organized.

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 verdicts, two processing paths, error states, no output schema), the description is remarkably complete. It explains return values, citation behavior, the meaning of every verdict type, and why this tool replaces multiple sequential calls. No important aspect 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?

The input schema already provides thorough descriptions for both parameters, including the claim example and tolerance_pct semantics (default, overrides, cap). The description repeats a similar claim example but adds little beyond the schema. Since schema coverage is 100%, baseline 3 is appropriate.

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

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

The description clearly states the tool performs natural-language claim verification against authoritative sources, with specific example phrasings like 'fact check' and 'verify the claim that…'. It distinguishes itself from sibling research tools by the return of verdicts (confirmed, refuted, etc.) and by consolidating multiple pipeline steps into one call.

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 whenever the agent needs to check whether something a user said is factually correct', and describes the two internal paths (SEC EDGAR vs. grounded pipeline). It does not explicitly name when NOT to use it or how it differs from sibling tools like ask_pipeworx_grounded, but the context is clear enough for an agent to select it.

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