Statbank Md

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

Annotations already mark the operation as read-only and non-destructive. The description adds valuable behavioral details: the default model is free, probing Anthropic requires a BYO key with direct payment, and the return format includes per-model score/confidence/signals. This goes beyond annotations, though rate limits or data persistence are not covered.

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, front-loaded with the primary function, then model-specific details, then use cases. Every sentence earns its place with no repetition or fluff.

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

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

With no output schema, the description compensates by specifying the per-model return structure ({score, confidence, signals, raw_response} plus combined view) and listing applicable use cases. It could add guidance on interpreting scores, but given annotations handle safety, the description is largely complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces `_apiKey` usage (pass to also probe Anthropic) and mentions the default model for `models`, but adds little beyond schema definitions for `entity` and `context`. Overall marginal added meaning, still meeting the baseline.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility 0-100 per model. The verb 'probe' and resource are specific, and it distinguishes itself from similar siblings like scan_competitor_ai_presence by focusing on generic visibility rather than competitor-specific scans.

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

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

Provides concrete use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains the default model and how to add Anthropic via `_apiKey`. However, it does not explicitly mention when not to use this tool or name alternative tools, preventing a top score.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description builds on this by revealing the tool routes to many underlying tools, returns 'structured answer with stable pipeworx:// citation URIs', promises 'one fast call', and notes it 'works on every tier'. 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 front-loaded with 'PREFER OVER WEB SEARCH' and uses visual emphasis. It is longer than minimal but every sentence provides value: use cases, trigger phrases, examples, alternatives, and expectations. Slightly repetitive examples prevent a 5.

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

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

Given the tool's complexity (routing to thousands of tools) and no output schema, the description covers everything needed: expected output format with citations, when to use, alternatives, examples, and availability across tiers. It fully prepares 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%: the 'question' parameter and all aliases are described. The description adds context on what kinds of questions to ask (e.g., 'current US unemployment rate') but does not add parameter-level semantics 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?

The description clearly states this tool answers factual questions by routing to 5,529 tools across 1,455 sources and returning structured answers with citations. It uses a specific verb ('routes') and explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH...', specific trigger phrases ('what is', 'look up', etc.), and concrete examples. It also states when to step up to alternatives ('Step up only when needed: for... ask_pipeworx_grounded; for... deep_research').

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds crucial context: it's a live experimental edge, currently matches ask_pipeworx exactly, falls back to nothing, and is a full working router. This goes well beyond the structured fields.

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 efficient, covering purpose, current state, usage, and behavioral details in a few sentences. Every sentence contributes meaningful information without redundancy.

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

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

Though there's no output schema, the description explains the response shape ('same response shape as ask_pipeworx') and the fallback behavior. Combined with the fully documented parameter schema, the tool is completely specified for an agent to invoke correctly.

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

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

All six parameters are documented as aliases for 'question' in the schema (100% coverage). The description only says 'same arguments' without adding detail, so the schema carries the full burden and the description provides minimal additional value.

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

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

The description clearly identifies this as a beta routing tool: 'identical universal router (same 5,529 tools...)' and references ask_pipeworx. It distinguishes it from siblings as the experimental edge variant, making its purpose unambiguous.

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

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

Explicitly states when to use: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the experimental nature and that results are compared against the stable router, providing clear context for choosing this tool over the stable ask_pipeworx.

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 (readOnlyHint, openWorldHint, idempotentHint), the description discloses refusal behavior with specific refusal_reason values, the exact success return shape, and the extra LLM call cost. It also explains that the answer is extracted only from tool result content, setting accurate expectations.

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

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

The description is dense but every sentence earns its place: purpose, mechanism, success/failure output, usage context, and cost tradeoff. It is front-loaded with the primary purpose and avoids redundant wording.

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

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

With no output schema, the description compensates by specifying the exact success JSON structure ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and failure refusal reasons. It also covers cost and when to use, making it complete for a high-stakes read tool.

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

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

Schema description coverage is 100% and all parameters are aliases for 'question.' The description does not add parameter-level detail, but the schema fully documents them. Baseline 3 applies since the schema handles parameter semantics.

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

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

The description clearly states it is a hallucination-resistant answer mode that extracts answers using only tool result content, returning answer with evidence. It explicitly distinguishes itself from the sibling ask_pipeworx by groundedness and refusal behavior.

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

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

It gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' It also notes the cost tradeoff (one extra LLM call), helping the agent decide between siblings.

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

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

The description extensively discloses behavioral details: resolver confidence contract ('market_match_confidence ∈ {high, medium, low, none}'), short-circuit statuses ('low_confidence_match', 'market_closed_or_inactive'), tradeability warnings ('illiquid_wide_spread'), news fallback mechanics ('_fallback_attempted', 'retry_after_sec'), and resolution-rule risk (refund_50_50 etc.). These go well beyond the readOnlyHint/openWorldHint annotations and significantly inform invocation and result trust.

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

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

The description is long but logically organized with explicit headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded purpose. Some examples are granular, but they earn their place by illuminating the fan-out behavior. A 4 reflects that it is structured and purposeful, though not as tight as a two-sentence description.

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

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

Without an output schema, the description carries the burden of explaining return values, and it does so thoroughly: result.market fields, result.analysis with model probability/edge, result.evidence keys, parent_event summary, news fallback fields, and various status flags. It also covers edge cases (closed markets, wide spreads, cancellation rules), making it complete for an agent to act on.

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 three parameters (market, depth, include_raw) with 100% coverage, so the description need not compensate. The prose recaps the market input formats but does not add new parameter-level meaning; the fan-out examples relate more to the depth behavior than to parameter syntax.

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

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

The description opens with a specific verb-resource pairing ('Research a Polymarket bet by pulling the relevant Pipeworx data') and enumerates accepted input formats. It also distinguishes this tool from sibling research tools by framing it for bet-oriented questions ('should I bet on X', 'what does the data say about Y', 'is there edge in Z').

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 'Use for' triggers ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). It, however, does not explicitly mention when not to use the tool or name alternative sibling tools, so it stops short of full exclusionary 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 mark the tool read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail: it pulls specific SEC filings/FAERS data, handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. No contradiction exists.

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

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

The description is longer than minimal, but each sentence adds essential information. It is front-loaded with trigger phrases and the key preference rule, followed by type-specific details and output characteristics. Slight redundancy in the example list, but no wasted content.

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

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

Despite lacking an output schema, the description clearly states what the tool returns (paired data, citation URIs, sorted results), covers data sources, and explains why it replaces many sequential lookups. This is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, and the description adds meaningful detail beyond the schema: it explains what each 'type' value pulls (company vs drug), and clarifies that 'values' accepts tickers/CIKs or drug names with examples. This helps the agent correctly populate parameters.

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

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

The description uses a specific verb ('compare') with a clear resource (companies/drugs), and explicitly distinguishes from sibling tools by emphasizing parallel side-by-side comparison and 'ALWAYS PREFER over sequential single-pack lookups'. It also clarifies the two entity types and data sources.

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 lists trigger phrases ('X vs Y', 'which is bigger', 'rank these companies') and provides an explicit preference rule over alternatives, as well as type-specific guidance. This gives unambiguous when-to-use direction.

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, openWorldHint=true, destructiveHint=false. The description complements these with account requirements, latency expectations, the never-invented guarantee with gaps[], contradiction[] behavior for standard/thorough, excerpting semantics, and the resolvability condition for citation_uri. 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 (~250 words) but dense with useful information. However, it delays the core purpose by starting with an ACCOUNT REQUIRED warning and sibling alternative; the tool's primary verb phrase only appears in the third sentence. Some repetition (e.g., reiterating 'gaps[]' and 'contradictions[]') could be tightened. Still, every major claim serves a purpose.

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

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

No output schema exists, so the description carries full responsibility for explaining return values, and it does: findings packet with verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop field, and the condition for citation_uri. It also covers prerequisites (account), timing (15-90s), and fallback behavior. For a tool of this complexity, this is comprehensive.

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

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

Although schema coverage is 100%, the description adds substantive meaning: it explains what the depth levels do ('quick=3 single hop', 'standard=5 adds a gap-recovery hop + contradictions scan', 'thorough=8 paid full iterative hop'), and for question it clarifies that broad/multi-part is acceptable and 'decomposition is the point'. This goes beyond the schema's enum descriptions.

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

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

The description opens with a clear verb phrase: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources...' and explicitly distinguishes itself from open-web search and from ask_pipeworx. It names the output ('findings packet') and the scope, making the tool's 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 states when to use: 'Best for broad/multi-part questions over structured data' and when not to: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also gives an alternative if not signed in: 'use ask_pipeworx instead'. This is textbook 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=true, idempotentHint=true, and destructiveHint=false, establishing a safe read-only operation. The description adds valuable behavioral context by disclosing that results include full schemas with curated examples, are ranked by relevance, and are 'ready to call directly, no second schema lookup needed.' No contradiction with annotations.

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

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

The description is three sentences, front-loaded with the core action, and each sentence earns its place. The long domain list is purposeful and informative for an agent, and there is no redundant text.

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

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

The description covers all essential aspects: what the tool does, when to use it (including priority), what it returns (ranked results with schemas), and how to act on the results (directly callable). No output schema exists, but the description sufficiently explains the return format for an agent to know what to expect.

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

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

Schema description coverage is 100%, with all six parameters documented and aliases provided. The description adds no new parameter-level meaning beyond restating that query is a 'Natural language description' (already in the schema), so baseline 3 for a well-covered schema applies.

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

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

The description clearly states a specific verb+resource: 'Find tools by describing the data or task.' It distinguishes itself from sibling tools by being a meta-tool that returns tool definitions ('names, descriptions, and full input schemas') rather than domain-specific answers, and explicitly instructs to call it FIRST.

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 when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' It also implies when not to use (when you already know the specific tool), providing clear 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 (readOnly, openWorld, idempotent, non-destructive) are complemented by the description's disclosure of fan-out behavior across sources, soft-fail for the USPTO PatentsView API sunset, news fallback GDELT→GNews, and return format specifics. 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 informative paragraph with a few example phrasings, a list of returned fields, and key caveats. It is slightly long but every sentence adds value; the structure is well-organized. Score 4 rather than 5 because it could be tightened without losing essential information.

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

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

No output schema exists, but the description enumerates all return components (cik, recent_filings with URIs, fundamentals, patents, news, LEI) and explains limitations and fallbacks. It fully prepares the agent for invocation and interpretation.

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 detailed property descriptions (ticker/CIK, only 'company' supported). The description reinforces examples like 'AAPL' or zero-padded CIK but adds no new semantic meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool creates a 'full cross-source profile of a US public company' via examples like 'Tell me about X' and details the exact outputs (CIK, filings, fundamentals, patents, news, LEI). It distinguishes itself from sibling tools by explicitly positioning against chaining 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?

Usage guidance is explicit: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and explicitly states names are not supported, directing to 'use resolve_entity first'. This provides clear when-to-use and alternative identification.

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 readOnlyHint=false, so the description's 'Delete' statement adds little beyond the structured data. It does add the nuance of 'clear sensitive data' and the pairing reminder, but no additional behavioral traits (e.g., what happens if the key doesn't exist) are disclosed. Since annotations carry the safety profile, this modest addition warrants a 3.

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 with no filler. The first sentence states the action, the second provides usage context and sibling references. Every word serves a purpose, making it highly 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?

For a simple single-parameter destructive tool with strong annotations, the description covers the core purpose, when to use it, and adjacent tools. No output schema exists, and none is needed here. The guidance is complete and sufficient for an agent to act correctly.

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

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

Schema coverage is 100% for the single 'key' parameter, which is already described as 'Memory key to delete.' The description only repeats 'by key' without adding extra meaning, so the baseline of 3 applies.

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

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

The description clearly states the tool's function: 'Delete a previously stored memory by key.' It uses a specific verb (delete) and resource (memory/key), and distinguishes it from siblings like remember and recall by focusing on deletion rather than storage or retrieval.

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

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

Explicit usage guidance is provided: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names related tools ('Pair with remember and recall'), giving the agent clear direction on when to invoke this tool versus its siblings.

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

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

The description discloses that the tool fetches the page, extracts title/description/key links, and emits standard llms.txt markdown, which complements the read-only/idempotent annotations with process details. It also clarifies the output is a single text blob for site-root placement, adding behavioral context beyond the safety hints.

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

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

The description is three sentences, each serving a distinct purpose: stating the function, explaining the process/output, and listing use cases. There is no wasted text, and the most important information is front-loaded.

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

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

Given the tool's simplicity (one required param, text output), the description covers what it does, how it works, and what the output looks like. It also includes use cases, making it self-contained for an agent to decide when to invoke it.

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

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

The input schema already documents both parameters with full coverage (url and max_links), so the description adds no new parameter-level meaning. It mentions the extraction process but doesn't elaborate on parameter syntax or edge cases, leaving the schema to carry the load.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, with a specific verb ('Generate') and resource ('llms.txt file'). It distinguishes itself from siblings by focusing on generating the standard file format for AI crawler indexing, a unique function among the listed 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 'Useful for:' section explicitly lists three concrete use cases (client sites, own projects, auditing competitors), giving clear when-to-use guidance. However, it does not mention when not to use it or alternative tools, 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?

With annotations already declaring read-only, idempotent, and non-destructive behavior, the description adds valuable context by specifying the exact fields returned (id, type, params, created_at, last_fired_at, fire_count) and clarifying that only the caller's subscriptions are listed. This goes 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-loading the core purpose, then listing return fields, and ending with practical usage guidance. Every sentence earns its place with no redundancy or filler.

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

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

For a simple list tool with a single optional parameter and no output schema, the description is sufficient: it states what is listed, what fields are returned, and the intended use cases. The annotations cover safety, and the schema covers the parameter, leaving no significant gaps.

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

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

The schema fully documents the single parameter (include_inactive) with a clear description of its meaning and default. The tool description does not add any additional parameter detail, but the schema coverage is 100%, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, providing a specific verb and resource. It distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on listing existing subscriptions for review, making the purpose unambiguous.

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

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

The description gives explicit use cases: reviewing current monitoring before adding more subscriptions and finding an id to cancel. While it does not name alternative tools directly, the context makes it clear when listing is appropriate, so it does not fully match the highest standard of explicitly naming 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 are all false/neutral, so the description carries the burden and does so richly: rate-limited to 5 per identifier per day, free/no quota, returns claim_token, team reads digests daily, roadmap impact. No contradiction with annotations.

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

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

The description is dense and front-loaded, with no filler, but it is relatively long and packed with multiple clauses. Every sentence serves a purpose; it could be slightly more scannable, but it is still efficiently structured.

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

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

With no output schema and a nested parameter object, the description fully compensates: it states what the claim_token return means, how to read the reply later, rate limits, scope limitations, and the type of message expected. An agent has enough to invoke and follow up correctly.

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

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

Schema coverage is 100%, but the description adds meaningful usage semantics: how to pass claim_token later, to avoid pasting end-user prompts, and to describe issues in terms of Pipeworx tools/packs. This goes well beyond the schema's baseline.

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

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

The description opens with a specific verb+resource ('Tell the Pipeworx team something is broken, missing, or needs to exist') and enumerates exact use cases (bug, feature/data_gap, praise). It clearly distinguishes itself from sibling tools by being the dedicated feedback/reporting channel.

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

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

Provides explicit when-to-use guidance for each feedback type and an explicit exclusion: if the tool came from a different MCP server, report it elsewhere. Also explains the claim_token flow for follow-ups, making alternatives and prerequisites 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?

Adds valuable behavioral context beyond annotations: it is a self-aggregating signal derived from CF analytics-engine, contains no PII, returns only (pack, tool, count), and has caching behavior (5min-1h). This complements the readOnlyHint and idempotentHint annotations with concrete details about data source and freshness.

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

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

Two sentences, front-loaded with the primary purpose, followed by concise bullet-style use cases and a cache note. No waste; every clause contributes actionable 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?

Although no output schema is provided, the description explicitly lists return contents ('top tools, top packs, and total call volume') and data format ('pack, tool, count'), plus caching windows. With only one parameter and low complexity, this fully covers what an agent needs to invoke and interpret results.

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

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

Schema covers the window parameter 100% with enum values and descriptions. Description adds extra meaning by explaining 'Shorter windows surface what's hot right now; longer windows show steady-state demand', which helps agents choose appropriately beyond just reading the enum.

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 what the tool does: 'What other AI agents are calling on Pipeworx right now' and returns top tools, packs, and call volume. It distinguishes from sibling tools like discover_tools by emphasizing the trending/aggregated nature and the self-aggregating signal from CF analytics-engine.

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

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

Provides explicit use cases (discovering hot data sources, confirming canonical tool choice, checking use case alignment) and explains window semantics for choosing between 24h/7d/30d. Does not explicitly name alternatives or exclusions, but the 'confirming before asking your own question' implies a contrast with ask_pipeworx 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?

Beyond annotations (readOnlyHint=true, etc.), the description discloses behavioral thresholds: >3pp partition deviation triggers a signal, ≥0.30 Jaccard similarity anchors cross-event pairs, and >20% placeholders returns null. It also warns concretely in FILL CHECK that realizable_edge_pp ≤ 0 means 'the overround exists only at last-trade, not in the book; do not trade 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 long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose. Every sentence adds operational detail, though it could be slightly tighter.

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

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

The tool is complex (3 modes, filters, response schema, fill check) and has no output schema, so the description fully compensates by listing response fields (opportunities[] with gap_pp, suggested_trade, reasoning) and the partition_check fields. It also cross-references polymarket_fill_risk, making it a complete guide for invocation.

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

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

Schema already covers both params at 100%, but the description adds substantial semantics: event slugs like 'fed-decision-may-2026', full URLs accepted, and topic seed questions with concrete examples like 'Fed rate decision'. It enriches the schema descriptions with mode-specific behavior.

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

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

The description opens with a clear verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It also delineates three modes (trending_scan, event, topic), distinguishing this arbitrage tool from sibling tools like polymarket_fill_risk for sizing.

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

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

It explicitly says 'For custom sizing use polymarket_fill_risk' and provides mode selection guidance ('event (recommended for a specific market)', 'topic (for cross-event scanning)'), with examples and when cross-event mode is preferable.

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

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

Despite strong annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description adds extensive behavioral context: detailed model family breakdowns, the 24h-move warning, FETCHED response structure, diagnostics funnels, and caching behavior ('Cached 1h at the KV level keyed on all knobs'). This goes far beyond what annotations alone communicate and gives the agent a clear mental model of what the tool does and how to interpret results.

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

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

The description is extremely long and lacks any formatting, appearing as a single dense paragraph. While it contains valuable information, it could be substantially condensed and organized into sections or bullets (e.g., model families, knobs, response structure). Several details such as per-sport alpha values and specific model gate relaxations are arguably too granular for an agent to select or invoke the tool, and the lack of visual structure makes it harder to parse.

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

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

Given the tool's complexity (3 model families, 9 optional parameters, diagnostics, and no output schema), the description is remarkably complete. It explains the top-level response structure (by_segment, fed_candidates/fed_note, _diagnostics), why certain segments may be empty, and how knobs affect results. It also covers caching and the rationale behind Fed signal exclusion, leaving no major gaps for an agent to understand what it will receive.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra semantic value by grouping some parameters as 'TRADEABLE-EDGE KNOBS' (min_liquidity/max_spread_pp) and explaining nuanced behavior like why min_kelly does not filter partition opportunities, while min_partition_leg_kelly does. This additional context helps the agent choose and set parameters appropriately 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 explicitly states the tool's function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly identifies the resource (Polymarket markets), the action (scan and return), and the unique value (Pipeworx disagreement). It also distinguishes itself from siblings like polymarket_arbitrage by focusing on edge detection from data disagreement, not arbitrage.

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

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

The description provides a clear use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains when certain knobs should be adjusted (e.g., 'Bump for very thin partitions; drop to 0 if you have a smarter fill model'). However, it does not explicitly compare itself to sibling tools such as polymarket_arbitrage or polymarket_edge_tracker, so some explicit exclusion guidance is missing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds substantial behavioral context: snapshots written on cache-miss, gaps meaning no scan, 60-day TTL bound, decay computed from daily closes not intraday, and detailed response semantics. This goes well beyond the annotation baseline.

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

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

The description is well-structured with ARGS, RESPONSE, and LIMITS sections. It is dense but every sentence adds value, and the purpose is front-loaded. No wasted words.

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

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

With no output schema, the description fully compensates by explaining the response structure (tracked[], expired[], snapshot_dates[]) and field semantics, plus limitations like TTL and data gaps. Complete for a read-only telemetry tool with two optional parameters.

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

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

Schema coverage is 100% with detailed descriptions for both parameters (days, window). The description restates defaults ('default 14, max 30', 'default 1wk') but does not add meaningfully beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence and decay rather than current edges.

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

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

The description provides clear context for when to use the tool ('how long has this edge existed and is it shrinking?') and contrasts fresh versus old edges. However, it does not explicitly name alternative tools or state when not to use it, though this is implied by the sibling tool list.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context beyond annotations: it walks the order-book ladder, returns detailed fill metrics (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd), and warns about partial basket fills causing unhedged directional positions.

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

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

The description is dense but well-structured: it leads with a one-sentence summary, then clearly separates SINGLE-MARKET, BASKET, and USE THIS sections. Every sentence provides necessary information about modes, parameters, return fields, or usage guidance. Despite its length, it earns every word.

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

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

There is no output schema, so the description must explain return values, which it does comprehensively: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum vs realizable_sum, capture_ratio, profit_usd, thin_legs[], max_clean_notional_usd, and forced_directional_risk. It fully covers the tool's behavior in both modes.

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%, but the description adds significant meaning beyond the schema. It clarifies that market and event are mutually exclusive modes, explains how size_usd is interpreted differently in single-market vs basket mode, and how side defaults are computed in basket mode. This is valuable context the schema alone does not 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 opens with a specific verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this tool from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk and order-book depth.

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

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

The description explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial fills create unhedged directional risk).

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

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

The description goes far beyond the annotations (readOnlyHint=true, openWorldHint=true). It discloses important behaviors: the tool computes spreads only when bet shapes are equivalent, warns when they aren't (compatibility_warning), provides temporal_alignment to detect mismatched resolve periods, and explicitly says spreads are meaningless when aligned=false. It even explains skipped_cross_type/subtype counters, which are critical for interpreting results. This is rich behavioral context well beyond the structural hints.

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

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

The description is dense and information-rich, but it is one long block without paragraph breaks, which slightly hurts scannability. However, it front-loads the core purpose in the first sentence, uses clear labels (TWO MODES, RESPONSE, SAFETY FIELDS) to structure the content, and every sentence adds substantive detail. It earns a 4 rather than 5 because the heavy use of parentheticals and the long safety-fields section could be tightened.

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

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

For a tool with no output schema, the description covers the return shape thoroughly: leg-by-leg prices, matched spread[], top_spreads_pp, compatibility_warning conditions, temporal_alignment, and skipped_cross counters. It explains edge cases (matched_pairs:0 scenarios) and the meaning of alignment. Given the tool's complexity and the absence of output schema, this description is remarkably 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?

All three parameters are fully described in the schema (100% coverage), but the description adds crucial semantics: it explains the two operational modes (topic vs explicit overrides) and gives examples of valid values for topic and the format for kalshi_event_ticker and polymarket_event_slug. It also clarifies that explicit parameters override the mapped side, which the schema does not state. This exceeds the baseline 3 for full schema coverage.

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

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

The description names a specific verb+resource ('Cross-venue spread between Kalshi and Polymarket') and clearly distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by focusing on same-question cross-venue spreads. It also enumerates two modes (topic shortcuts vs explicit tickers), which precisely scopes the tool's function.

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

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

The description explicitly tells when to use the tool ('when bet shapes are equivalent that delta is a real signal') and when not to ('when they aren't the tool says so'). It also warns that 'pre-mapped ≠ tradeable' and that most shortcuts return compatibility warnings, which disambiguates from sibling tools like polymarket_arbitrage. The two-mode instruction is clear guidance, and the safety-field explanation tells the agent what to check before acting.

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

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

The description goes beyond the readOnlyHint/idempotentHint annotations by explaining the response size cap and the requirement to structure the body as a PxWeb query. It also discloses the return format json-stat2, adding behavioral context not present 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?

Three sentences, each conveying essential information: the action, the required body format, and a critical constraint. No filler content.

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

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

For a query tool with no output schema, the description covers the request format, the response format (json-stat2), and a key limitation. It could detail error conditions or how to interpret json-stat2, but the core information for a standard query is 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 coverage is 100%, but the description supplements it by explaining the body structure and emphasizing the need to narrow dimension values using codes from table_meta. This clarifies parameter semantics beyond the schema's property 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 action: 'POST a PxWeb query to a Moldova National Bureau of Statistics (Statbank) table and return observations as json-stat2.' It names the specific resource and output format, distinguishing it from sibling tools like table_meta.

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 it: when you need observations from a PxWeb table. It explicitly directs users to 'narrow each dimension's values using codes from table_meta,' indicating a prerequisite and an alternative tool. It also gives a constraint ('PxWeb caps responses at ~10,000 cells') that informs usage decisions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds scoping details (anonymous IP, BYO key hash, account ID) and the behavior of omitting the key to list all keys—context beyond what annotations provide. It is not overly rich but adds meaningful value.

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

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

The description is three sentences, front-loaded with the primary action. Each sentence earns its place: the first states what it does, the second explains when to use it, and the third adds scoping and pairing context. No wasted words or redundancy.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete enough. It explains the core retrieval and listing behavior, scoping, and relationship to siblings. It does not specify return format, but the behavior—retrieving a value or listing keys—is unambiguous. Given the lack of an output schema, a brief note on return type would be slightly beneficial but is not necessary for correctness.

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

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

Schema coverage is 100% and the schema description already explains the key parameter and the omit-to-list behavior. The description provides examples of keys ('user's target ticker, an address, prior research notes') but adds no additional parameter syntax or format details, so it does not exceed 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 tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses a specific verb and resource, and distinguishes itself from sibling tools 'remember' and 'forget' by describing its complementary role.

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

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

Explicitly says 'Use to look up context the agent stored earlier' and provides concrete examples of what to store (target ticker, address, research notes). It also names alternatives and complements: 'Pair with remember to save, forget to delete.' This gives clear when-to-use guidance and differentiates from siblings.

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

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

The description discloses that mark_read:true mutates read state, which directly contradicts the readOnlyHint annotation. This is a serious inconsistency, and per the rubric, any contradiction with annotations yields a score of 1.

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

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

The description is concise, front-loaded with action, and each sentence adds useful information—purpose, payload, filtering, side effects, and alternative URL. No fluff, so a score of 5 is warranted.

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 the return format, filtering options, mark_read side effect, and even an alternative access method. Despite the annotation contradiction, the description itself is thorough for a tool without an output schema, so a score of 5 is appropriate.

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 parameters have schema descriptions (100% coverage), and the description adds examples for type, explains ISO timestamp for since, and clarifies mark_read's effect on future calls. This goes beyond the schema, so a score of 4 is justified.

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 pulls fired events from the subscription feed and returns recent alerts with source, citation_uri, and raw payload. It is distinct from siblings like list_subscriptions or recent_changes by focusing on alert events.

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 context on when to use it (polling) and offers an alternative endpoint for scripts/dashboards, which implies usage. However, it does not explicitly contrast with sibling tools or mention when not to use it, so a score of 4 is appropriate.

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, openWorld, idempotent, not destructive), the description discloses fallback behavior (GDELT preferred, GNews on rate-limit/5xx), soft-fail for PatentsView sunset, and return structure (changes[] grouped by source, total_changes, citation URIs). This is substantial added context.

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

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

The description is long but dense and front-loaded. Every sentence earns its place: trigger phrases, core purpose, source details, fallback behavior, param format, return format, and alternative tool. No fluff.

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

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

For a tool with no output schema, the description specifies return shape, param semantics, edge cases (rate-limit fallback, API sunset), and when to use an alternative. It is comprehensive enough for correct invocation.

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

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

Schema coverage is 100%—all three parameters have descriptions. The description adds a minor recommendation ('Use "30d" or "1m" for typical monitoring') but otherwise mirrors the schema, so the baseline 3 applies.

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

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

The description clearly states the tool provides a change feed for a company over a time window, listing specific sources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly distinguishes from entity_profile. The verb 'returns a change feed' and resource 'company changes' are specific and 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 opens with natural-language triggers ('What's new with X', 'latest on Y') and provides an explicit alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' This gives clear when-to-use and 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?

The description discloses persistence behavior (authenticated users persistent, anonymous sessions 24 hours) and scoping ('scoped by your identifier'), adding value beyond annotations. Annotations already declare idempotentHint=true and destructiveHint=false, so the description enriches the safety profile without contradicting 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 three sentences, front-loaded with purpose, then usage, then key behavioral details. Every sentence adds distinct value, with no redundancy or fluff.

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

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

For a simple 2-parameter tool with no output schema, the description covers purpose, usage, persistence, scoping, and relationships to sibling tools. It is complete and self-sufficient, providing all necessary context for an agent to invoke it correctly.

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

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

The input schema covers both parameters fully (key and value, each with descriptions and examples). The description mentions 'key-value pair' and value flexibility but adds little beyond the schema's 100% coverage. Baseline of 3 is appropriate given the schema already provides strong semantics.

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

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

The description clearly states the tool's function with a specific verb ('Save data') and resource ('data the agent will need to reuse later'), and explicitly distinguishes it from siblings by mentioning pairing with 'recall' and 'forget'. The scope ('across this conversation or across sessions') is also clarified.

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 guidance on when to use the tool ('Use when you discover something worth carrying forward') with concrete examples, and explicitly names alternatives ('Pair with recall to retrieve later, forget to delete'), offering clear usage vs. alternative context.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds substantial context: it explains the cross-source identity spine, source labeling, explicit 'unresolved' reporting, graceful degradation when GLEIF/OpenFIGI are unavailable, and that it cascades through multiple endpoints—all 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?

The description is long but logically organized: it starts with user intents, then a use directive, then bullet-like SUPPORTED TYPES with details, and ends with fallback behavior. Every section adds value, but some redundancy exists between the schema and description (e.g., accepted input formats) and the length could be tightened.

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

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

With no output schema, the description makes an effort to explain what each type returns (CIK/ticker/LEI/FIGI for company; RxCUI/ingredient/brand/citation for drug) and mentions unresolved handling and fallback. It stops short of specifying an exact return structure, but for a name-resolution tool this is 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?

The schema has 100% coverage with descriptions for both parameters, so the baseline is 3. The description largely repeats the schema's input formats (e.g., ticker, CIK, or name; brand or generic) rather than adding new parameter-specific meaning. It does elaborate on output behavior, but that's not parameter semantics.

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

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

The description opens with concrete example queries then states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input,' clearly specifying the verb (resolve) and resource (entity names to IDs). It distinguishes itself from siblings like ask_pipeworx and entity_profile by emphasizing 'Use FIRST whenever you have a name but need an ID.'

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

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

It provides explicit guidance with 'Use FIRST whenever you have a name but need an ID' and describes supported entity types and accepted input formats. However, it never names alternative tools to use when no ID is needed, so it lacks explicit exclusions or 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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond annotations: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density per entity. It does not mention external API calls or rate limits, but for a read-only, non-destructive tool with these annotations, the added return-format and ranking insight justifies a 4.

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

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

The description is three sentences, front-loaded with the main purpose, followed by procedural details and a use-case example. Every sentence earns its place: purpose, mechanism with ai_visibility_check, and return format. No fluff, no redundancy with schema or annotations.

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 adequately covers return values ('ranked list with score, confidence, signal density per entity') and the use case. It also clarifies the entity-role nuance ('your brand + N competitors'). However, it does not explain edge cases such as entity count limits (though schema does), tie-breaking, or error handling. For a moderate-complexity comparison tool with rich annotations, this is fairly complete but has minor gaps.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters (entities, models, _apiKey, context). The description does not add significant meaning beyond the schema; it mentions 'your brand + N competitors' which aligns with the entities parameter but does not explain syntax or formats further. Baseline 3 is appropriate when 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 the tool's purpose: 'Compare AI visibility across multiple entities side-by-side' and specifies that it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. This distinguishes it from the sibling tool ai_visibility_check, which likely handles single-entity checks. The verb 'Compare' and resource 'AI visibility' are specific and actionable.

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

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

The description provides clear context for when to use the tool: 'Useful for competitive AI-marketing audits' with a concrete example ('does Claude know about us as well as our competitors?'). It implies use when comparing multiple entities side-by-side, but does not explicitly state when NOT to use it or name alternatives beyond the underlying ai_visibility_check. This is clear context without exclusions, scoring a 4.

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 behavioral insights beyond the annotations: it notes that the tool fans out to multiple sources, that partial failures degrade gracefully, and specifically that bundlephobia's first measurement on a new version can take 5-30s and may cause a timeout that appears in sources_failed while the rest returns. These are not derivable from the readOnly/openWorld/idempotent hints, making the description more transparent.

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 efficiently structured: the first sentence states the composite purpose and sources, the second gives usage triggers, the third describes the return payload, and the final sentence handles ecosystem scope and failure behavior. Each sentence earns its place, and the key 'what is it' is front-loaded.

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

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

Given the tool's complexity (multiple remote sources, partial failures, timing) and the absence of an output schema, the description is remarkably complete. It names all output categories (summary block fields, per-advisory detail, links, alternative versions), explains partial failure handling, and clearly states the v1 ecosystem limitation with a pointer to a direct alternative. Nothing critical is missing.

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

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

The input schema already covers both parameters with clear descriptions (package name, version with default behavior). The description adds no new parameter-level semantics beyond what the schema states, so the baseline of 3 is appropriate. It does not need to compensate for schema coverage because coverage is 100%.

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, composite purpose: 'should I add this npm package to my project' check in ONE call, which clearly differentiates it from other tools. It names the two data sources (deps.dev and bundlephobia) and the exact dimensions covered (license, advisories, bundle size, etc.), leaving no ambiguity about what the tool does.

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

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

The description explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also provides a clear exclusion and alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This gives both positive and negative usage guidance with a named alternative.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses key behavioral details: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings over 500-char overlapping windows, and has a 200K char cap with truncation flagging. This enriches the agent's understanding of how the tool operates.

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 efficiently structured: each sentence serves a purpose—first states the core function, second covers usage and benefit, third provides integration context, fourth gives technical specifics. No filler or redundancy.

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

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

Despite no output schema, the description fully explains the return value (top-N passages with offsets and similarity scores) and constraints (200K char cap). Combined with comprehensive annotations and detailed parameter descriptions, the tool is fully understood for 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?

Even with 100% schema coverage, the description adds meaningful context: text is described as a 'fetched record' with examples (SEC 10-K, article, tool result), query gets natural-language examples, and limit is implied as top-N passages. The technical details (embeddings, windows) further contextualize the input parameters.

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

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

The description clearly states the tool's function: 'Semantic search INSIDE a fetched record.' It specifies the verb 'search', the resource ('a fetched record'), and distinguishes itself from siblings by explaining it operates on already-pulled text, pairing with ask_pipeworx_grounded for grounding. This is specific and 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?

Explicitly tells when to use: 'Use when the record is too big to cram into the prompt.' It also contrasts with an alternative (ask_pipeworx_grounded) and explains the benefit: saves context, returns only relevant passages with offsets for verification. This gives clear guidance on when and how to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral details about the tree structure (dbid, type 'l' folders, type 't' tables with '.px' suffix) that are not present in the annotations, enriching the agent's understanding.

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 action, and every word contributes meaning. It is concise without sacrificing key details about navigation and file type identifications.

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

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

For a single-parameter, read-only navigation tool with strong annotations and a detailed schema, the description covers all essential operational aspects. It explains what to expect at each path level, making it sufficient for safe and 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?

The schema description for the 'path' parameter is thorough, covering default behavior and format with an example, giving 100% coverage. The tool description reinforces the same semantics but does not add new information beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: navigating the database/subject tree. It specifies that the root lists databases, and drilling into a database id yields folders and tables, which distinguishes it from sibling tools like query_table or table_meta.

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

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

The description provides clear usage context: start at the root to list databases, then navigate into a database id to explore folders and tables. It does not explicitly mention when not to use it or alternative tools, but the navigational intent is evident and unambiguous.

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 annotations include idempotentHint=true, yet the description says 'Create a proactive monitoring subscription' and 'Returns the new subscription id', implying each call creates a new subscription and is therefore non-idempotent. This is a direct contradiction between the description and the annotation. While the description does disclose auth requirements and delivery details, the contradiction mandates a score of 1.

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 organized: it leads with the core purpose, then enumerates subscription types and delivery channels. Every sentence carries useful information, but the density of options and parentheses makes it somewhat harder to scan quickly. It is not overly verbose given the tool's complexity.

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

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

The description covers the essentials: the action, return value (subscription id), auth requirement, subscription types, and delivery channels including how to consume the feed. It omits webhook details that appear in the schema, but the schema's high coverage compensates. It is sufficiently complete to guide correct invocation.

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

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

The input schema already provides detailed descriptions for all parameters (100% coverage), including examples for each subscription type. The tool description adds minor clarifications like 'items:["5.02"] = officer change', but largely duplicates schema content. With high schema coverage, the description's contribution is marginal, so a baseline of 3 is appropriate.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream', which is a specific verb-resource pair. It distinguishes the tool from siblings like 'list_subscriptions' and 'unsubscribe' by focusing on creation, and also lists supported subscription types and the return value.

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

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

The description clearly indicates when to use the tool (to create a subscription) and includes context such as requiring an OAuth account and delivery channel options. However, it does not explicitly name alternatives like 'list_subscriptions' or 'recent_alerts' for comparison, so it falls short of the highest bar for exclusions.

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

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

Annotations already declare readOnlyHint/idempotentHint, and the description adds useful behavior: results are drawn from the live catalog, are category-bucketed, and include the exact tool + argument shape for each example. It doesn't mention output limits or pagination, but it goes beyond the structured hints enough to warrant a 4.

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

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

The description is longer than average, but every sentence carries operational value: example phrasings, return contents, call modes, and when to use first. It is front-loaded with the user's likely questions and remains free of filler, though it could be tightened slightly.

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 one optional parameter, no output schema, and complete annotations, the description fully covers what an agent needs: what will be returned, how to request the full spread vs. focused output, and when to invoke the tool. It is complete for this low-complexity onboarding 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?

Although the schema already names the optional 'topic' parameter, the description adds practical semantics: examples ('finance', 'pharma', 'betting'), the effect of passing a topic ('focus'), and the crucial behavior of omitting it ('full spread'). This meaningfully exceeds 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 opens with concrete example queries and clearly identifies this as 'the onboarding entry point' that 'Returns category-bucketed example questions'. The verb 'Returns' plus the scope (what can I ask Pipeworx) distinguishes it from siblings like discover_tools and makes the intended 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?

It explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.)'. It also gives clear call-mode guidance: no args for the full spread versus passing topic to focus.

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 the description adds the path format constraint and states the return shape (dimensions with codes and value lists). It doesn't discuss auth/rate limits but provides meaningful behavioral context beyond the annotations.

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

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

Three sentences, front-loaded with the core purpose, followed by a practical path example and downstream usage. No filler.

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

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

For a one-parameter metadata fetch with no output schema, the description adequately covers the path format, return content, and how to use the result with query_table. It might mention error cases or if the table must already exist, but overall it's 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?

The input schema gives only an example, but the description clarifies what the path must be (ending in '.px') and why. This adds real semantic value beyond the schema's terse example, so the single parameter is well explained.

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

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

The description opens with a specific verb ('Fetch') and resource ('dimension definitions and valid coded values for a Moldova Statbank PxWeb table'), clearly distinguishing it from the sibling query_table which would fetch data. It even ties usage to query_table, so the tool's role is unambiguous.

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

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

The description provides a concrete path requirement (must end in '.px' table id) and explains that output is used to build query_table's selection body. This gives clear context on when to use it, though it doesn't explicitly list exclusions or alternatives beyond query_table.

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 reveals behaviors beyond annotations: ownership enforcement and the soft-delete nature (deactivated, not deleted) with historical data preserved. Annotations already indicate non-read-only and non-destructive, so the description adds meaningful context about the side effects and constraints. It does not detail error behavior for invalid or unauthorized IDs, so a slight gap remains.

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

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

The description is two sentences, front-loaded with the primary action, and every sentence provides necessary behavioral or contextual information. There is no fluff or redundancy.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers the core purpose, ownership constraint, and post-cancellation behavior. It integrates well with sibling tools like recent_alerts, making the tool fully understandable for an agent.

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

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

The schema already provides full coverage with a clear description: 'Subscription id (uuid) returned by subscribe.' The tool description does not add further meaning to the parameter, simply referring to 'id' in the action. Since schema coverage is 100%, a baseline of 3 is appropriate.

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

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

The description clearly states the action: 'Cancel a subscription by id' with a specific verb and resource. It distinguishes from sibling tools like subscribe and list_subscriptions by focusing on cancellation, and the ownership constraint adds specificity.

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 this tool: to cancel a subscription by id, with an important ownership limitation. It also explains that deactivation (not deletion) preserves historical events, linking to recent_alerts. However, it does not explicitly mention alternatives or when not to use it, so it stops short of full guideline coverage.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat those. It adds significant behavioral context: the distinction between 'could_not_verify' (pipeline failure) and 'unsupported' (no source exists), the exact verdict set, the presence of pipeworx:// citations, and the instruction that 'could_not_verify' must not be presented as evidence. This exceeds 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 longer than the calibration examples, but every sentence earns its place: trigger phrases, use case, routing logic, return format, special verdict meanings, and the replacement of sequential calls. It is front-loaded with user-intent phrasing and includes a clear 'IMPORTANT for callers' caveat. No filler or redundancy.

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

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

With no output schema, the description fully explains the return value: verdict list, actual value with citation, and reasoning. It clarifies edge cases (could_not_verify vs unsupported) and error handling. Given the tool's complexity, two parameters, and rich annotations, this description is complete and self-contained.

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

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

Schema coverage is 100%, with both parameters (claim and tolerance_pct) already described in the schema. The description adds extra meaning for tolerance_pct by explaining how it overrides the implied tolerance and how to set it for hallucination detection (1–2%). It also gives the context that the claim parameter is natural language and routes internally, adding semantic value beyond the schema.

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

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

The description uses a specific verb ('validate', 'verify', 'fact check') and clearly states the resource being acted on: natural-language factual claims. It distinguishes itself by detailing the two distinct pipelines (SEC EDGAR/XBRL fast path for company-financial claims and a grounded pipeline for all others), which differentiates it from generic search or lookup 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 'Use whenever the agent needs to check whether something a user said is factually correct' and gives a clear routing rule (financial vs. other claims). It also warns that 'could_not_verify' means the check did not happen and should not be treated as evidence. However, it does not name specific sibling alternatives or explicitly state when not to use this tool versus them, so it falls just short of a 5.

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