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?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds meaningful behavioral context: routing to a large toolset, auto-filling arguments, returning structured answers with stable citation URIs, and handling live news. It does not discuss failure modes or rate limits, but the combination of annotations and description is sufficient.

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

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

The description is long but well-organized and front-loaded with the most important directive ('PREFER OVER WEB SEARCH'). It flows from behavior to trigger phrases to examples to alternative selection. There is some repetition between 'Use whenever...' and 'START HERE', but each sentence contributes useful signal for a broad default 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?

Despite being a complex meta-tool with no output schema, the description covers everything an agent needs: when to use it, what question format to provide, what behavior to expect (routing and argument filling), what output to expect (structured answer with citation URIs), and how to choose among close alternatives. 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?

The input schema documents 'question' and its aliases at 100% coverage, so the baseline is 3. The description adds the valuable operational nuance that the tool 'fills arguments' itself, meaning the agent only needs to supply a natural-language question; the example queries reinforce the expected format.

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

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

The description states a clear and specific purpose: answer factual questions about real-world entities/events/numbers using authoritative structured data with citations. It explains the mechanism (routes to 5,767 tools across 1,506 verified sources, fills arguments, returns pipeworx:// citation URIs) and differentiates from web search and ask_pipeworx_grounded.

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

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

It explicitly says 'PREFER OVER WEB SEARCH' and gives trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') plus a broad class of acceptable questions. It also says 'START HERE for most questions' and names alternatives: web search as fallback, ask_pipeworx_grounded for maximal citation fidelity, and notes breaking-news handling.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond that: it is a full working router with no fallback, it may have experimental routing candidates live, and currently no candidate is active so it matches ask_pipeworx exactly. This is exactly the kind of live experimental context an agent needs before invoking it.

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

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

The description is dense but not bloated: it front-loads the beta identity and equivalence to ask_pipeworx, then covers current candidate state, usage instruction, and fallback behavior. Every sentence earns its place and addresses a likely agent question about whether this experimental variant is safe and fully functional.

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?

Together with the complete schema and annotations, the description covers what the tool is, when to use it, how it may differ from stable behavior, and what to expect in terms of response shape via the ask_pipeworx equivalence. Nothing necessary for correct invocation is missing.

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

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

The input schema already documents all six parameters and aliases at 100% coverage, so the description does not need to repeat them. The description only says 'same arguments' as ask_pipeworx, which adds no per-parameter semantic detail beyond the schema. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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 this is a beta version of ask_pipeworx: a universal router over the same 5,767 tools with the same arguments and response shape. It also distinguishes itself from the stable ask_pipeworx by explaining that candidate routing improvements may be enabled live. An agent can tell exactly what resource and function this tool exposes.

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

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

The description gives explicit when-to-use guidance: use it exactly like ask_pipeworx when you want the newest routing, and results are compared against the stable router. It does not explicitly enumerate when-not-to-use cases or alternatives beyond the stable ask_pipeworx, but the beta-versus-stable contrast makes the intended context clear.

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

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

Beyond the annotations, the description discloses the exact success return shape, enumerates all refusal_reason values, and explains that answers are extracted only from tool results. It also reveals the extra LLM-call cost, which is meaningful behavioral context not visible in annotations.

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

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

The description is dense but every sentence earns its place: mode, routing behavior, output contract, refusal semantics, use cases, and cost tradeoff. It front-loads the defining property and keeps the most operational details organized and readable.

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

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

Given there is no output schema, the description fully explains return values and failure modes. Combined with rich annotations and clear routing guidance, nothing essential is missing for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100% and the parameters are all well-documented aliases of 'question,' so the schema already carries full parameter meaning. The description does not add parameter-specific details, but none are needed; the baseline 3 applies.

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

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

The description opens with a specific, differentiated purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It names the resource (Pipeworx), the action (retrieve data, extract grounded answer), and explicitly contrasts itself with ask_pipeworx so the agent can distinguish the two at a glance.

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

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

It provides explicit when-to-use guidance for quoted, cited, or acted-on answers and lists concrete high-stakes domains. It even names the preferred alternative for casual lookups and gives a cost-based reason, so an agent can route correctly without inference.

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?

Beyond the readOnly/idempotent annotations, the description discloses account/pricing requirements, the NOT-open-web constraint, the parallel 5,767-tool routing, output packet fields (verbatim evidence, confidence, source, fetched_at, citation), the gaps[] promise, depth-specific hops and contradictions[], and latency expectations. This is far more behavioral detail than 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 dense and front-loaded with the critical account gating, but it is a long single paragraph with awkward midsection fragments ('mit follows up', 'Last: when passed depth not stated, use standard?') and some redundancy. It contains a lot of valuable information, but it would benefit from tightening and restructuring.

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

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

With no output schema, the description carries the burden of explaining the return packet, and it does: findings fields, gaps[], contradictions[], citations, and latency. It also covers prerequisites, alternatives, parameter semantics, and data scope. For a 2-parameter tool this is complete enough for correct selection and invocation.

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

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

Though schema coverage is 100%, the description adds substantial meaning beyond the schema: it explains that question accepts broad/multi-part natural language with examples, and it gives a detailed semantics of depth (quick/standard/thorough with facet counts, hops, gap recovery, contradictions, and paid tier). This helps a model pick valid, useful parameter values.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources ... in ONE call.' It explains the decomposition and parallel tool routing, and differentiates itself from both open-web search and ask_pipeworx. An agent can clearly tell this is the multi-source research tool, not a single-lookup tool.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx instead.' It also states the account prerequisite and directs unsigned-in users to ask_pipeworx. These are concrete selection criteria against siblings.

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

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

Annotations already declare readOnlyHint=true, 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 already mark it read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: fan-out across multiple sources, soft-fail for patents, expected-empty fda_products for companies without biologics, sources_used/sources_failed semantics, private-company resolved:false behavior, and type interchangeability. Nothing contradicts the annotations.

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

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

The description is long but front-loaded with the core routing message and most important behavior. The dense semicolon-separated return-field enumeration earns its place because there is no output schema, though it could be slightly better organized for scanning.

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

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

Given the tool's complexity and the absence of an output schema, the description is exceptionally complete. It documents inputs, output fields, failure semantics, edge cases, source fallbacks, and the private-company path, so an agent has what it needs to invoke the tool and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the schema by giving examples ("AAPL", "0000320193", "Moderna") and explaining that type accepts company/ticker interchangeably, but it adds limited new meaning beyond what the parameter descriptions already 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 states a specific verb and resource: it builds a full cross-source profile of a US public company in one parallel call. It clearly distinguishes itself from single-pack SEC/XBRL/news lookups by saying 'ALWAYS PREFER' for holistic views, so an agent can tell it apart from sibling tools.

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

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

The description explicitly says when to use it: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives concrete example user phrasings. It does not enumerate exclusions or alternatives by name, but the guidance is clear enough for routing.

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

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

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 only declare readOnly/idempotent/non-destructive, but the description adds extensive disclosure: compatibility_warning and compatibility_codes can both be non-empty even when pairs match, pairing is keyword-based (pairing_unverified), fees are not modeled (gross vs net), skipped counters reveal dropped comparisons, and temporal_alignment null semantics are clarified. This goes well beyond what annotations 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?

Purpose is front-loaded and sections are loosely labeled (RESPONSE, SAFETY FIELDS, Codes), but the text is very long and repetitive — compatibility codes and temporal_alignment are explained multiple times, sometimes with overlapping wording. Several sentences could be merged without losing information. It is structured but not tight.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It does that thoroughly: leg-by-leg prices, top_spreads_pp, compatibility_warning/codes[], per-entry flags[], skipped counters, fees_note, and temporal_alignment semantics. Given the complexity of the matching logic and safety fields, nothing essential for calling the tool correctly is missing.

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

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

The schema already has 100% description coverage for all three parameters. The description adds meaning by explaining the interaction: 'topic' is a pre-mapped shortcut that auto-fetches matching events, while explicit ticker/slug override the topic-mapped side. This clarifies the mode semantics beyond the schema's individual parameter descriptions.

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

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

The first sentence states exactly what the tool does: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the verb (compute spread), resource (two named venues), and the condition (same resolving question). It also distinguishes scenarios (when bet shapes are equivalent vs not), making it clear how it differs from related tools like polymarket_arbitrage.

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

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

The description explicitly lays out two usage modes (topic shortcuts vs explicit ticker/slug), explains the overrides, and gives important context: 'Real cross-venue spreads are rarer than the macro-shortcut list suggests... pre-mapped ≠ tradeable.' It does not explicitly name sibling alternatives to avoid, but the mode guidance and caveats provide clear context on when to use the tool.

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

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

Annotations already declare 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?

Beyond the annotations (read-only, idempotent, open-world), the description adds substantial behavioral detail: multi-source resolution across EDGAR/GLEIF/OpenFIGI/RxNorm, graceful degradation when enrichment sources are unavailable, explicit `unresolved` output for missing identifiers, and non-assertion with `figi_candidates` on ambiguous name matches. It also warns that trailing security-class words will fail FIGI lookup. This far exceeds what annotations alone 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 long but appropriately front-loaded with trigger phrases and the primary instruction 'Use FIRST.' Every clause adds substantive detail, including edge cases and degradation behavior. It is somewhat dense and could be better organized into clearer sections, which keeps it from a perfect conciseness score.

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

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

For a tool with two required parameters and no output schema, the description is remarkably complete. It covers supported entity types, source provenance, ambiguity handling, unresolved identifiers, enrichment failures, and the internal multi-endpoint cascade. An agent has enough context to select and invoke the tool correctly and to interpret expected outcomes.

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%, yet the description still adds meaningful parameter semantics beyond the schema. It explains accepted input forms (ticker, CIK, ISIN, name; brand or generic drug), gives concrete examples, and includes the crucial caveat to pass only the entity name for bonds, since 'trailing security-class words match nothing.' The `type` enum is also elaborated with per-type resolution behavior.

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

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

The description uses a specific verb-plus-resource framing: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also supplies concrete trigger phrases ('What's the ticker for…', 'find the CIK for…') and distinguishes itself from sibling tools by explaining that it maps names to IDs, not profiles or comparisons.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also clarifies scope through supported types and examples, and notes that one call replaces 2-3 manual lookups. However, it does not name alternatives or state when not to use it, so it lacks explicit exclusions.

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

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

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.