Metals Api

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

Annotations already declare readOnlyHint and idempotentHint, so the mutation risk is covered. The description adds valuable context: the default model is free, Anthropic requires a BYO key with direct billing, and returns a specific per-model structure (score, confidence, signals, raw_response). This goes 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 three sentences with no filler. It front-loads the core function, then layers on model specifics and use cases. Every clause adds useful information (default model, BYO key, return shape, audit use cases).

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 explains the return type (per-model object + combined view) and the conditional _apiKey requirement. It covers model selection, cost nuance, disambiguation via 'context', and practical applications—sufficient for a read-only, idempotent probe tool with strong annotations.

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

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

Schema coverage is 100%, so parameter descriptions exist. The tool description adds extra meaning by clarifying the _apiKey billing implication ('you pay Anthropic directly'), noting the free default model, and explaining the models array behavior ('Omit for just workers-ai'). This enriches understanding beyond the schema.

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

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

The description states a specific action ('Probe one or more LLMs') and a specific outcome ('score visibility (0-100) per model'). It clearly distinguishes itself from siblings like ask_pipeworx or deep_research by focusing on AI visibility auditing with a numeric score.

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 concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model vs. optional Anthropic probing. However, it does not explicitly mention alternatives or when not to use, leaving room for slight ambiguity.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. Description adds significant behavioral context: routes to thousands of tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, works on all tiers, and is a single fast call. It also notes it handles live news. No contradiction with annotations.

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

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

The description is long but well-structured: front-loaded with the main purpose and usage guidance, followed by examples and sibling comparisons. Each sentence adds value (routing behavior, output format, alternatives, examples). Slightly verbose but justified for a high-complexity router tool.

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

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

For a tool that routes to thousands of sources, this description is remarkably complete: it covers what it does, when to use it, what it returns, how it differs from alternatives, and includes concrete examples. No output schema exists, but the description covers return format (structured with citations). Nothing missing for an agent to call 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?

Schema covers 100% of parameters (all aliases of 'question'), and the schema already states that the field accepts natural language with aliases. The description adds examples but no additional semantic guidance beyond what the schema 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's purpose: routing questions to authoritative sources and returning structured answers with citations. It names the verb (ask), the resource (Pipeworx's 5,581 tools across verified sources), and the scope (current/historical data, SEC filings, etc.). It also distinguishes from siblings by offering fallback to ask_pipeworx_grounded and deep_research for different needs.

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 (factual questions, lookups, 'current' queries) and when to step up (hallucination-resistant single answer → ask_pipeworx_grounded; broad/multi-part → deep_research). Positions this as the default entry point, working on every tier, and even covers breaking news via news feeds. No ambiguity about alternative selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds critical behavioral context: the beta status, live candidate routing experiments, and the fact that it currently matches ask_pipeworx exactly. It also clarifies that it is a full working router with no fallback, which is 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 front-loaded with the core purpose and beta distinction, then provides essential usage and current-state details. Though it is somewhat lengthy, every sentence contributes meaningful context—such as the retirement date and comparison-to-stable workflow. The structure is organized and readable, but 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?

For a beta router with no output schema, the description covers all necessary context: what it is, how it differs from the stable version, current state, usage guidance, and fallback behavior. It references the sibling ask_pipeworx for exact usage, which is sufficient. Combined with rich annotations, the agent can 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?

The input schema already documents all six parameters with full coverage and complete alias descriptions. The description does not add any parameter-specific semantics, but given the high schema coverage, the baseline of 3 is appropriate. No further compensation is needed.

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

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

The description defines ask_pipeworx_beta as a beta version of ask_pipeworx, specifying it is an identical universal router with the same 5,581 tools, arguments, and response shape. It differentiates itself from the stable sibling by highlighting its experimental nature and candidate routing improvements. The verb and resource are clear: it answers a question by routing it across 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 instructs to 'use it exactly like ask_pipeworx when you want the newest routing' and states that results are compared against the stable router. It also clarifies that no candidate is currently active so it matches ask_pipeworx exactly, preventing misuse. This gives the agent clear conditions for selection over the sibling.

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 behaviors: it returns a structured object with evidence and confidence, can refuse with a specific refusal_reason, and uses only the fetched tool result to prevent hallucination. It also reveals the cost tradeoff of one extra LLM call. This substantially enriches the agent's understanding of how the tool behaves in failure and success cases.

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

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

The description is information-dense and every clause contributes a distinct fact: grounded extraction, routing, response shape, refusal reasons, use cases, and cost tradeoff. The primary concept is front-loaded ('Hallucination-resistant answer mode'), and the alternative guidance appears at the end. There is no filler or redundant restatement of the title.

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

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

For a tool with refusal behavior and multiple return cases, the description covers the answer shape, failure modes, when to use it, and how it differs from the cheaper sibling. It even enumerates refusal_reason values and the evidence field. An agent has everything needed to invoke and interpret the tool correctly, especially since the required parameter is a simple question.

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 all parameters are already documented in the schema with descriptions like 'Your question in natural language' and aliases. The description adds no new parameter-level semantics beyond aligning the 'question' concept with the tool's purpose. A baseline 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description states a specific purpose: a hallucination-resistant answer mode that routes over the same toolset as ask_pipeworx and extracts answers only from the tool result. It clearly distinguishes this grounded variant from the plain ask_pipeworx by emphasizing evidence, confidence, and refusal behavior. The verb and resource are identifiable without needing to inspect siblings.

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

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

The description explicitly says when to use this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete domains such as financial verdicts, legal claims, and medical lookups. It also says when not to use it: 'prefer ask_pipeworx for casual lookups', citing the extra LLM-call cost. This is explicit when/when-not 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses extensive behavioral details: fan-out parallelism, response shapes, resolver contract (market_match_confidence), safety short-circuits for low-confidence and closed markets, wide-spread illiquidity warnings, and cancellation-rule risk. This exceeds the annotations' basic safety profile and gives the agent important decision-traps to watch for.

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 with bold section headers (FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.), making it scannable. Every section adds substantive caveats or data about behavior, though some redundancy exists (e.g., two blocking path explanations). It is more verbose than ideal, but the structure mitigates and the content is dense.

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 main response fields (result.market, result.analysis, result.evidence) and their semantic meaning (e.g., edge_pp, kelly_fraction_half). It covers special cases (parent_event, news fallbacks, closed markets, cancellation rules) and provides interpretative guidance ('ALWAYS inspect market_match_confidence'). For a complex, fan-out research tool, this is nearly exhaustive.

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 all three parameters with descriptions, achieving 100% schema coverage. The tool description's parameter-related content (e.g., market as slug/URL/question text) largely repeats the schema examples and adds no new syntax or constraints. The fan-out examples indirectly map market categories to sources but don't change parameter meaning, 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 opens with a specific verb+resource phrase: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly defines the input (slug/URL/question text) and output (evidence packet + market-vs-model comparison). The use-case examples ('should I bet on X') further clarify its intended scope relative to other sibling research 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 states the intended use cases: 'should I bet on X', 'what does the data say about Y', etc. It also provides classifier categories and fan-out examples to help the agent understand when the tool is appropriate. However, it does not explicitly name when NOT to use this tool or mention alternative sibling tools, so it falls short of the 5-level.

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

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

Even with annotations (readOnlyHint, idempotentHint) covering safety, the description adds valuable behavioral details: pulls LATEST 10-K data from SEC EDGAR/XBRL, handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. This goes well beyond the annotations and clarifies data sources and output behavior.

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

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

The description is front-loaded with query examples, immediately followed by the core purpose and preference guidance. Each subsequent sentence adds critical info (per-type data, sorting, return format, efficiency benefit) without redundancy. It's dense but organized, and every sentence earns its place.

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

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

Given the tool's moderate complexity (two entity types with distinct data sources) and lack of an output schema, the description is complete: it explains input triggers, data sources, output format (paired data + citation URIs), and sorting behavior. No critical gaps for an agent to invoke the tool correctly.

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

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

While the schema describes both parameters (coverage 100%), the description enriches them significantly: it explains what each type pulls (company financial metrics vs drug FAERS/FDA/trial counts) and gives concrete examples for values (tickers/CIKs vs drug names). This adds meaning beyond the schema's terse descriptions.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2–5 companies or drugs in a single parallel call. It provides specific trigger examples ("X vs Y", "which is bigger") and distinguishes itself from single-entity lookups (e.g., entity_profile) by explicitly saying it should be preferred for comparisons.

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

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

It provides direct usage guidance: "ALWAYS PREFER over sequential single-pack lookups when comparing entities" and notes it replaces 8–15 sequential lookups. The trigger phrases ("Compare X and Y", "rank these companies") give clear when-to-use context, effectively differentiating from alternatives.

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

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

Fully discloses behavior: accounts required, paid tier conditions, parallel tool routing, return packet format (verbatim evidence + confidence + source + fetched_at), the gaps[] convention, contradictions[], and the explicit guarantee that citations are always fetchable. The 'never invented' clause and the fetchable-citation guarantee are exactly the kind of behavioral specifics agents need. One small omission: no statement on rate limits, but no annotations are present to cover this.

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 densely packed with essential operational detail that the schema cannot convey (parallel routing, citation format, gap behavior, hop mechanics, tier gating). Everything present earns its placeant, though a reader scans a wall of text before hitting the critical usage caveats (account requirement, paid tier, news limitation). The key warning about current news is buried mid-paragraph rather than front-loaded, and the length could reduce readability.

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

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

For a complex tool that decomposes questions and returns findings packets, the description is remarkably complete: it explains the return format (verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop field), the depth parameter's semantics, second-hop iteration, latency expectations, and the account/tier requirements. It even notes the edge case where output is mostly empty gaps[] for non-catalog topics. An agent has everything needed to decide when to call it and what to expect back.

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 already describes both parameters. The description adds value by explaining depth:'standard' vs 'thorough' in plain language (re-angle vs chase leads, contradiction pass) and clarifying that decomposition is the point of asking multi-part questions. It does not repeat the enum values verbatim, which the schema already lists, but adds the semantic difference — a good compensation for an otherwise sparse 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?

States a specific verb ('research') on a specific resource ('Pipeworx's 1463 STRUCTURED data sources'), and clearly distinguishes itself from open-web research by emphasizing structured data sources serious research. It also explicitly names sibling alternatives (ask_pipeworx) and states what it is NOT ('this is NOT open-web search'), so an agent can tell them apart without opening schemas.

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 this tool ('Best for broad/multi-part questions'), when NOT to use it ('For BREAKING or colloquial CURRENT-EVENTS... prefer ask_pipeworx'), and directly names the alternative. Also covers auth prerequisites (account required, paid tier for 'thorough'). This is exemplary 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 and idempotentHint=true, so readers know it's a safe, read-only operation. The description adds valuable behavioral context: it returns top-N results with full input schemas and curated examples, and explicitly notes that results are 'ready to call directly, no second schema lookup needed.' This gives the agent a sense of what the response will look like and how to act on 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 front-loaded with the core purpose, then expands into usage context, return behavior, and priority guidance. It is slightly longer than the TDQS high example but every sentence adds value—no filler. The structure guides the agent from 'what' to 'when' to 'what to expect.'

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

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

The tool has no output schema, so the description carries the burden of explaining return values, which it does well ('returns the top-N most relevant tools with names, descriptions, and full input schemas'). Given the tool's complexity (a meta-tool with many sibling tools), the description effectively covers purpose, usage, and output format, leaving little ambiguity for an agent.

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

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

Schema description coverage is 100%, with all six parameters documenting their meaning (query, aliases, limit). The description reinforces that the primary input is a natural language description of data/task and enumerates example domains, but it does not add new details beyond the schema. The schema already provides the parameter semantics, 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 'Find tools by describing the data or task,' which clearly identifies the tool's purpose (discovering other tools based on a natural language query). It distinguishes discover_tools from siblings by framing it as a meta-tool for browsing the available option set, not a domain-specific tool.

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

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

The description explicitly states when to use the tool ('Use when you need to browse, search, look up, or discover what tools exist') and provides a clear directive ('Call this FIRST when you have many tools available and want to see the option set'). It contrasts with 'not just one answer,' implying that for direct answers the agent should use a domain-specific tool instead.

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

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

Annotations already provide readOnly, openWorld, idempotent, and non-destructive hints. The description adds meaningful behavioral context: it fans out across multiple sources, includes fallback from GDELT to GNews, mentions the PatentsView API sunset with soft-fail behavior, and discloses that names are not supported. This goes well beyond the annotations.

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

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

The description is lengthy but well-structured, front-loaded with example queries and a clear purpose. Each sentence adds operational value (sources, output fields, fallbacks, constraints). Slight redundancy in the opening phrases, but overall efficient for the complexity.

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

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

With no output schema, the description carries the burden of explaining return values, which it does comprehensively: cik, company_name, recent_filings with URIs, fundamentals with metrics, patents with sunset caveat, news fallback, and LEI. It also covers input constraints and failure modes, making it complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, with both parameters fully documented. The description mostly reiterates the schema ('Pass ticker ... or zero-padded CIK') and adds the 'US public company' context, but it does not introduce new parameter-level semantics beyond what the schema already states. Baseline 3 is appropriate.

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

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

The description clearly states it produces a 'full cross-source profile of a US public company' and provides example queries that map to natural language requests. It explicitly differentiates from siblings by recommending this tool over 'chaining single-pack SEC/XBRL/news lookups' and directing name-based queries to resolve_entity.

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

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

It specifies exactly when to use ('when the user asks for a holistic view') and gives an explicit alternative ('use resolve_entity first' for names). It also states the 'ALWAYS PREFER' guidance, which clearly positions the tool against alternative approaches.

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

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

Annotations already disclose destructiveHint=true and idempotentHint=true. The description adds the 'clear sensitive data' usage context but does not go beyond annotations to explain permanence, error handling, or other side effects.

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

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

The description is two sentences with the core function stated first, followed by usage guidance. Every sentence earns its place with no superfluous content.

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

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

For a simple tool with one parameter and good annotations, the description covers purpose, usage, and pairing. It could mention idempotency or return behavior, but given the destructive and idempotent hints, these are not essential for an agent to use the tool correctly.

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

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

Schema coverage for the single 'key' parameter is 100% with the description 'Memory key to delete.' The tool description essentially repeats this, adding no further semantic detail beyond the schema.

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

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

The description states a specific action: 'Delete a previously stored memory by key.' It clearly distinguishes this tool from siblings by referencing 'remember' and 'recall' as paired operations, making the resource and verb explicit.

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 when to use this tool: 'when context is stale, the task is done, or you want to clear sensitive data.' It also names sibling tools ('remember', 'recall') for pairing, providing clear context for when to choose this tool over alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds process transparency: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies the output is a readable text blob. 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 three sentences, each serving a purpose: purpose, process, and use cases. It is front-loaded with the core functionality and wastes no words. Structure is ideal for quick agent scanning.

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

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

The tool is simple (2 params, 1 required), annotations cover safety, and the description explains the output format ('single text blob ready to drop at site-root/llms.txt'). No output schema exists, so the description adequately explains what the agent will receive. Given the low complexity, this is complete.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds minimal parameter-specific nuance beyond the schema—it implies that 'url' is the target site and mentions extraction of key links. Since the schema fully documents both parameters, a baseline of 3 is appropriate; the description neither compensates for gaps nor conflicts.

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

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

The description opens with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL.' It clearly states the tool's function (fetch, extract, emit) and distinguishes it from sibling tools by its unique output format and purpose. This leaves 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 provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It does not mention when not to use it or name alternative tools, but the use-case list gives clear guidance on appropriate contexts.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and openWorld hints. The description adds value by specifying the return format ('spot prices per troy ounce for that day'), which is not in the annotations or schema. 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 two sentences, front-loaded with the primary purpose, and every sentence adds information. There is no redundant or filler 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 tool is simple, has a rich output schema, and clear annotations. The description sufficiently covers what the tool does, what it returns, and why it might be used. Nothing critical is missing for an agent to select and 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?

Schema coverage is 100%, so all parameters are already documented with types and descriptions. The tool description adds no additional parameter-level meaning beyond the schema, making the baseline score of 3 appropriate.

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

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

The description states a specific verb and resource: 'Get metal prices for a specific historical date.' It distinguishes from siblings like get_latest by emphasizing the historical date scope. The output is clearly defined as spot prices per troy ounce.

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 usage context: 'Useful for tracking price changes or computing returns.' It implies when to use historical data vs. other tools, but does not explicitly name alternatives or exclusions. Still clear enough for an agent to decide when this tool fits.

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, covering safety. The description adds that prices are per troy ounce and that base/symbols are optional. This is useful but does not disclose potential rate limits, response format details, or any non-obvious behavior beyond the annotations.

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

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

The description is two sentences, front-loaded with the primary purpose, and includes only the essential extra details (per troy ounce, optional parameters). No filler or redundancy; every word adds value.

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

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

This is a simple data retrieval tool with rich annotations, a fully documented input schema, and an output schema. The description sufficiently covers the core behavior, units, and optional parameters. No significant gaps remain, and the description is complete for what the tool does.

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 already fully documents 'base', '_apiKey', and 'symbols'. The description's mention of optional base currency and symbols is redundant with the schema. It adds no additional semantics or syntax details beyond what the schema already provides, so the baseline score 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 retrieves 'latest precious and base metal spot prices' with specific metals and a per-ounce unit. The verb 'Get' combined with the resource and scope provides a clear, specific purpose. It also implicitly differentiates from siblings like get_historical by emphasizing 'latest'.

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 usage when current spot prices are needed, and notes optional parameters for base currency and symbols. However, it does not explicitly mention when not to use it or name alternative tools (e.g., get_historical for historical data). Usage is clear but not explicitly differentiated 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that results are scoped to the caller, include only active subscriptions by default, and detail the exact fields returned (id, type, params, created_at, last_fired_at, fire_count). This is useful behavioral context beyond annotations, though it doesn't discuss pagination or limits.

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 tight sentences. The first states purpose and output fields; the second gives concrete use cases. No filler or repetition of 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?

Simple tool with one optional parameter and no output schema. Description fully covers what the tool does, what it returns, and when to use it. Combined with strong annotations, this is complete for an agent to select and invoke.

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

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

Schema covers 100% of parameters with include_inactive described as 'Include cancelled subscriptions in the response (default false).' The description echoes this by saying 'active subscriptions' but adds no technical detail beyond the schema, so baseline 3 is appropriate.

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

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

Description opens with 'List the caller's active subscriptions' — a specific verb (list), resource (subscriptions), and scope (caller's active). It also enumerates return fields, distinguishing it from siblings like subscribe/unsubscribe and clarifying it's a read-only enumeration.

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 second sentence explicitly says when to use: 'before adding more' (implying subscribe) and 'to find an id to cancel' (implying unsubscribe). This gives clear situational guidance, even if alternatives aren't named by tool name.

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, so the description carries the full burden. It discloses the claim_token workflow for retrieving status, the 5/day rate limit, that it is free and doesn't count against quota, and that the team reads digests daily. This is substantial behavioral context well 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 long but well-structured: it front-loads purpose, then usage boundaries, then procedural details. Each sentence contributes necessary context, though there is slight redundancy (e.g., 'Pipeworx tool names are the ones this connection lists'). Still appropriately sized for a feedback tool needing careful guardrails.

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 the absence of an output schema, the description is fully self-sufficient: it explains the claim_token lifecycle, how to check resolution, rate limits, cost, and expected message formatting. It also prevents cross-server misuse, making the tool complete for an agent to invoke correctly.

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

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

Schema covers all 4 parameters with descriptions, so the baseline is 3. The description adds valuable semantic guidance for `message` (don't paste end-user prompt, describe in terms of Pipeworx tools) and contextualizes `claim_token` usage, elevating it above schema alone.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which is a specific verb plus resource. It clearly distinguishes this feedback tool from the sibling research/info tools by stating its purpose as reporting bugs, feature gaps, and praise.

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

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

The description explicitly lists when to use the tool (bug, feature, data_gap, praise) and when not to (tools from other MCP servers), even instructing to file with that server instead. This is clear guidance with exclusions and an alternative, going beyond simple 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description adds valuable behavioral context: data source (CF analytics-engine), no PII, output format (pack, tool, count), and caching behavior (5min-1h). 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 front-loaded with the core purpose, then returns details, use cases, and technical caveats. Every sentence provides necessary information without redundancy, and the structure with numbered use cases aids readability.

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 read-only tool with one parameter and no output schema, the description is highly complete: it specifies return content, window options, use cases, data provenance, privacy, caching, and even the internal data format. This fully compensates for the missing output schema.

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

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

Schema coverage is 100% with a single 'window' parameter that already includes enum values and a description explaining hot vs steady-state demand. The description repeats this and does not add new parameter-specific details, 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 the tool's function: it returns top tools, top packs, and total call volume for Pipeworx agent calls. It distinguishes itself from siblings like discover_tools by focusing on trending/aggregate call data, and it specifies the output scope.

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

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

The description provides explicit use cases ('Useful for:') such as discovering hot data sources and confirming canonical tools. It does not explicitly name alternatives or when-not-to-use, but the context is clear and actionable.

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

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

The description goes well beyond annotations by disclosing key behavioral traits: the partition filter that drops placeholder slugs, the 'skipped_low_similarity' surface for rejected pairs, and the fill check that prices signals against live CLOB depth with a warning not to trade when realizable_edge_pp <= 0. No contradiction with the readOnly/idempotent annotations.

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

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

The description is dense but every sentence earns its place. It is well-structured with clear mode breakdowns (trending_scan, event, topic), semantic anchor, partition filter, response format, and fill check. No fluff or repetition; front-loaded with the core purpose.

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

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

Despite having no output schema, the description fully explains the response structure: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context), and in event mode partition_check{...}.' It also covers edge cases (thin legs, similar pairs) and provides a pointer to a related tool for custom sizing, making it complete for an agent to invoke correctly.

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

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

Although schema coverage is 100%, the description adds substantial semantic value: it explains that `event` accepts full Polymarket URLs, gives concrete slug examples ('fed-decision-may-2026'), and clarifies that `topic` is for cross-event scanning with seed question examples. This goes far beyond the schema's parameter descriptions.

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

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

The description explicitly states the tool's function: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It uses a specific verb ('Find') and resource ('Polymarket'), and clearly distinguishes between its three modes (trending_scan, event, topic). This differentiates it from sibling tools like polymarket_fill_risk, which is mentioned as an alternative for custom sizing.

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

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

The description gives explicit 'when to use' guidance: 'Call with NO args for a trending_scan... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' It also provides a clear alternative: 'For custom sizing use polymarket_fill_risk.' This is more than sufficient to guide an agent.

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

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

The description goes far beyond the annotations, disclosing detailed internal logic: three model families with formulas, placeholder-slug filters, Kelly caps (0.25), slippage handling, 24h-move warnings, diagnostics structure, and a limitation note (Fed signal unreliable). It also explains why segments can be empty and how filtering gates work. This is exemplary behavioral transparency.

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 long, but every sentence carries substantive information. It is organized with labeled segments and parenthetical details, but the wall-of-text format could benefit from more visual structure (e.g., headers, bullet points). Given the tool's complexity, the length is justified, though slightly more concision would improve readability.

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 detailing the top-level response structure (by_segment, fed_candidates, _diagnostics), explaining empty-segment diagnostics, and covering caching behavior. It also documents all major behavioral aspects, including data sources and limitations, making the tool's context complete for an agent.

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

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

The schema already describes all 9 parameters (100% coverage), so the baseline is 3. The description adds significant semantic value by defining key concepts like edge_pp_net, explaining that min_kelly does not apply to partition_overround by design, and clarifying the distinct role of min_partition_leg_kelly. It also provides example thresholds for min_liquidity and max_spread_pp, enhancing understanding 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 is exceptionally clear: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further specifies the intended use case ('what should I bet on today') and differentiates from siblings by emphasizing its discovery function without paging hundreds of markets, unlike arbitrage or risk-specific tools.

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

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

The description provides strong contextual guidance: it states the tool is 'Built for "what should I bet on today"' and explains when it is appropriate (e.g., discovering opportunities, with caching noted). It also mentions an exclusion (Fed bets surface but are excluded from ranking) and offers knob adjustments. However, it does not explicitly name alternative tools for different use cases or say 'use X instead', so it lacks explicit exclusions/alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description goes beyond by explaining data source gaps ('snapshots are written when polymarket_edges runs on a cache-miss'), TTL limits ('60-day snapshot TTL'), and the specific computation basis ('daily closes of edge_pp_net, not intraday'). This is rich behavioral context that adds significant 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 dense but well-structured with labels (Args, RESPONSE, LIMITS) and front-loaded purpose. Every sentence provides actionable information—no filler. Despite length, it earns its space by explaining response fields and edge cases.

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

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

With no output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) including field meanings and calculations. It also covers limitations (TTL, cache-miss gaps) and data interpretation, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds minor context like 'snapshot family' for window and reasserts defaults, but does not provide substantial meaning beyond the schema. Baseline 3 is appropriate since the schema carries the descriptive 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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It uses a specific verb ('answers') and a concrete resource (edge persistence/decay), distinguishing it from sibling tools like polymarket_edges by focusing on time-series behavior 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: 'Answers "how long has this edge existed and is it shrinking?"' This implies when to use the tool (when edge age and decay matter). It does not explicitly name alternative tools or state when not to use it, but the relationship to polymarket_edges is evident from the description, making the usage context reasonably 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral detail beyond this: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), and warns that partial basket fills convert an arb into an unhedged directional position. This goes far beyond annotation coverage and is genuinely useful.

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 purpose, and every clause carries information. However, it is a single long paragraph with many semicolons and embedded lists; structured bullets would improve readability. It is not padded, but could be better organized.

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

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

With no output schema, the description enumerates the full set of return fields for both single-market and basket modes (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, forced_directional_risk). It also covers defaults, clamping, and risk logic, making the tool 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 parameter descriptions, but the description adds significant semantics: it explains how `size_usd` is interpreted differently in single-market vs basket mode, clarifies default side selection, notes clamping (10–1,000,000), and tells what each mode returns. This adds meaning beyond the schema.

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

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

The description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' naming a specific action and resource, and clearly distinguishes single-market vs basket modes. It also explicitly references sibling tools ('polymarket_arbitrage', 'polymarket_edges') and states when to use this tool instead, making its purpose unmistakable.

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

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

The description gives explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why—theoretical overround on thin books is not capturable and partial basket fills create unhedged directional risk—making the when-to-use vs alternatives very clear.

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

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

The description goes well beyond the annotations. It discloses the response structure (leg prices, spread), safety fields (`compatibility_warning`, `temporal_alignment`, `skipped_cross_type`), and the meaning of various edge cases. It clearly states when spreads are 'mathematically meaningless across the temporal gap' and explains why no arb exists in certain conditions. This is highly transparent and adds significant behavioral context.

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

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

The description is long but well-organized with clear sections (two modes, response, safety fields). It front-loads the core purpose. Minor redundancy exists (e.g., repeating 'pre-mapped ≠ tradeable' in the last sentence), but each sentence conveys distinct, valuable information. Slight over-length prevents 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 (multi-mode, no output schema), the description is highly complete. It covers all response fields, edge cases, compatibility warnings, and temporal alignment. It explains both why matches may fail and what the counters mean. The description fully compensates for the lack of an output schema.

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

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

Schema coverage is 100%, but the description adds critical meaning beyond the schema. It explains that `topic` is a pre-mapped macro shortcut list and enumerates all shortcuts. It clarifies that explicit ticker/slug overrides are for custom pairings. It also describes the two modes and how parameters interact, which is not evident from the schema alone.

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

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

The description clearly states the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the exact resource (two prediction markets) and the operation (computing spread), and distinguishes itself from siblings by focusing on cross-venue comparison rather than single-venue arbitrage or edge tracking.

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

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

The description explicitly explains two usage modes (`topic` shortcuts vs explicit `kalshi_event_ticker` + `polymarket_event_slug`) and when to use each. It gives clear guidance on when the tool may not be useful: 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It also explains when the response signals non-equivalent bet shapes or temporal misalignment, preventing misuse.

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

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

Annotations already provide readOnly/idempotent/destructive hints, so the bar is lower. The description adds meaningful context beyond annotations: scoping to the identifier ('anonymous IP, BYO key hash, or account ID') and the pairing relationship with remember/forget. It does not disclose behavior for missing keys, but this is minor given the simple read operation.

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

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

The description is two well-structured sentences, front-loaded with the core action. Every clause adds functional value—retrieval, listing, scope, and pairing—with no redundancy or filler.

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

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

Given the simple one-parameter tool with no output schema, the description is complete: it explains how to retrieve, how to list all keys, the scope of data, and the relationship to sibling tools. No critical information is missing for correct selection and invocation.

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

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

Schema coverage is 100% (the 'key' parameter is described), so baseline is 3. The description reinforces the parameter semantics with examples of stored content ('user's target ticker, an address, prior research notes') and restates the omit-to-list behavior, adding 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 clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It distinguishes from siblings by naming the paired tools: 'Pair with remember to save, forget to delete.' This gives a specific verb, resource, and scope.

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

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

Explicit when-to-use guidance is provided: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also gives alternatives/contrast with 'remember' and 'forget', and explains the omit-key behavior for listing all saved keys.

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

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

Annotations already indicate read-only, idempotent, and non-destructive. The description adds context about the side effect of mark_read (flagging events read and affecting subsequent calls), which is a useful behavioral trait beyond the annotations. No contradictions.

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

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

The description is concise at four sentences, front-loaded with the core purpose. Every sentence contributes useful information, including the alternative endpoint, with no redundancy.

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

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

With no output schema, the description adequately explains return fields and key parameters. It covers polling behavior, filtering, mark_read side effects, and an alternative access method. Minor omissions like unread_only behavior are not critical given schema coverage.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the type parameter with an example, and importantly clarifies mark_read's effect on future calls, which is not fully captured in the schema. This enriches parameter understanding.

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

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

The description clearly states the tool retrieves fired events from a subscription feed and returns the most recent alerts with specific fields. While it doesn't explicitly distinguish from siblings like get_latest or recent_changes, the resource and scope are clearly defined.

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

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

Provides clear usage context: suitable for polling, and the mark_read behavior is explained for sequencing. It also mentions an alternative endpoint for scripts/dashboards, giving some guidance on when not to use the tool, though it doesn't explicitly compare with sibling tools.

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

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

Beyond the readOnly/idempotent annotations, the description reveals concrete behavioral details: parallel fan-out to SEC EDGAR, GDELT→GNews fallback on rate limits/5xx, USPTO soft-fail due to API sunset, and the exact return structure (changes[] grouped by source, total_changes count, citation URIs). This is rich, non-obvious context that annotations alone do not provide.

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

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

The description is long but every sentence earns its place: example queries, core function, source details, fallback logic, return format, and an alternative tool. It is front-loaded with the main purpose after the examples and avoids redundancy. The structure is logical and scannable.

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

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

There is no output schema, so the description takes on the burden of explaining return values: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs.' It also covers source-specific behaviors and failure modes, making it complete for a tool with this complexity.

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

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

Schema coverage is 100% with well-documented params, so baseline is 3. The description adds value by giving concrete examples for 'since' ('7d', '30d', '3m', '1y'), recommending '30d' or '1m' for typical monitoring, and clarifying 'zero-padded CIK' for value. This goes slightly beyond schema descriptions.

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

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

The description clearly states the tool provides a change feed (filings, news, patents) for a company within a time window, using a specific verb ('fans out') and resource list. It distinguishes itself from entity_profile by explicitly naming it as the alternative for static profiles, making the purpose unmistakable.

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

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

The description gives explicit use case examples ('What's new with X', 'updates on Acme') and an explicit exclusion: 'Use entity_profile instead when you want the static profile... regardless of window.' It also explains fallback behavior (GDELT to GNews) and soft-fail conditions, which helps an agent decide when to invoke this tool.

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

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

Annotations declare non-read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond these flags: persistence differences for authenticated vs anonymous users (persistent vs 24-hour), and scoping by identifier. It doesn't detail overwrite behavior, but the added persistence context is valuable.

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

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

Four tightly focused sentences, front-loaded with the core action, then usage, persistence model, and pairing with complementary tools. Every sentence contributes information without 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 two-parameter tool with full schema coverage and annotations, the description covers purpose, usage, persistence, and related tools. It could mention overwrite behavior or return value, but the absence is not a significant gap for this simple storage operation.

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 parameter descriptions already include examples. The description reinforces the key-value concept and scoped storage but does not add significant new meaning 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 opens with a specific verb+resource ('Save data the agent will need to reuse later'), defines the storage model (key-value pair scoped by identifier), and clearly differentiates from sibling tools recall and forget by describing the write/memory action.

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

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

Provides explicit when-to-use guidance ('Use when you discover something worth carrying forward') with concrete examples like ticker, address, preference, research subject. It also names companion tools recall and forget, establishing when to use alternatives.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and openWorldHint. The description adds significant behavioral context: graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), internal cascading through multiple endpoints, and explicit handling of unresolved identifiers. 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 relatively long but well-structured: starts with example queries, then clear usage instruction, followed by detailed type explanations and behavior notes. It front-loads key points. Some details about internal cascading could be condensed, but overall it's efficient and organized.

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

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

Given no output schema, the description fully explains what the tool returns: canonical identifiers (CIK, ticker, company name, LEI with ownership, FIGI) and a list of unresolved identifiers. It covers behavior across entity types and failure modes (graceful degradation). No gaps remain for an agent to understand the tool's capabilities.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that for the 'value' parameter, company accepts ticker, CIK, ISIN, or name; drug accepts brand or generic; and that ISIN resolves to legal entity via GLEIF. This enriches the schema's brief descriptions.

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

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

The description clearly states the verb 'resolve' and resource 'entity' with specific examples like 'resolve a user-spoken NAME to the canonical/official identifiers.' It distinguishes from siblings by explicitly saying 'Use FIRST whenever you have a name but need an ID,' differentiating it from tools like compare_entities or entity_profile.

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

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

The description provides strong when-to-use guidance: 'Use FIRST whenever you have a name but need an ID' and lists example queries. It doesn't give explicit when-not-to-use or alternatives, but the context of being the first step and the mention that it 'replaces 2-3 manual lookups' implies its primary role. Slightly more explicit exclusions would elevate to 5.

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

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

Annotations already provide read-only and idempotency hints. The description adds valuable behavioral context by explaining that it internally calls ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. It does not contradict annotations, and it discloses the output structure 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 three sentences long: the first states the core action, the second provides a use case, and the third lists the return value. It is front-loaded, concise, and contains no filler, making it easy for an agent to quickly grasp the tool's function.

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

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

Given the tool's moderate complexity and lack of output schema, the description sufficiently covers its behavior, return values, and typical use case. The schema handles parameter details, and annotations cover safety. Minor gaps such as score interpretation or edge cases remain, but overall the description is complete enough for correct tool selection and invocation.

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

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

Schema description coverage is 100%, so all parameters are already documented. The description adds extra semantic value by specifying that the first entity is treated as the 'subject' for narrative and the rest as competitors, which is not present in the schema. It also uses an example to illustrate the 'context' parameter, enhancing understanding.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, with specific verbs like 'Compare' and 'Probes'. It distinguishes itself from sibling ai_visibility_check by focusing on multi-entity comparison and ranking, 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 a concrete use case ('competitive AI-marketing audits') and an example question, clearly indicating when this tool is appropriate. It also mentions it probes each entity via ai_visibility_check, implying single-entity checks belong to that sibling. However, it does not explicitly rule out other compare tools like compare_entities, so it lacks a formal exclusion.

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

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

Beyond the annotations (read-only, idempotent, open-world), the description discloses latency (bundlephobia's first measurement can take 5-30s), graceful degradation (partial failures return with sources_failed listing timeouts), and the composite nature with a detailed output summary. It even mentions that the rest still returns, which is behaviorally valuable and not covered by annotations.

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

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

Though dense, every sentence carries essential information: purpose, sources, use cases, output structure, latencies, ecosystem scope, and failure behavior. It is front-loaded with the core purpose and structured logically, earning its length for a composite tool.

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

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

With no output schema, the description fully explains return values (summary fields, per-advisory detail, links, alternatives). It covers edge cases (first measurement latency, timeout handling), ecosystem limitations, and the composite fan-out design, making it complete for the tool's complexity.

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

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

The input schema already provides 100% coverage for both parameters, so the baseline is 3. The description reinforces 'npm ecosystem only' and mentions 'is_latest' in output, but it does not add new parameter-level meaning beyond what the schema states.

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

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

The description clearly states the tool's purpose: a composite check for adding an npm package, combining license, advisories, version history, bundle size, dependency count, and ESM/tree-shaking support from two named sources. It distinguishes itself from all sibling tools by its specific domain (npm dependency vetting) and composite nature.

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

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

The description explicitly says when to use: whenever an agent asks about safety, popularity, size, or cost of adding a package. It also provides a direct exclusion for non-NPM ecosystems, directing users to 'deps.dev:version directly' for PyPI/Maven/Cargo/Go, fulfilling the 'when-not-to-use' criterion.

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 significant detail beyond annotations: return format (passages with character offsets and similarity scores), technical mechanism (BGE-base-en embeddings, cosine over 500-char windows), and input limits (200K chars, truncation flagged). This is exactly the kind of behavioral context that helps an agent trust 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?

Five sentences, no filler. The core operation is front-loaded; usage guidance, tool pairing, and technical details each earn their place. Perfectly compact for the information density.

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

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

Given no output schema, the description mentions the return structure (top-N passages with offsets and similarity scores). It also covers edge cases (truncation), tool pairing, and parameter types. An agent has everything needed to invoke correctly.

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

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

Schema coverage is 100% so baseline 3. The description adds value with concrete examples of `text` (SEC 10-K body, article) and `query` ('supply-chain risk', 'fiscal year 2024 revenue'), plus the truncation flag for oversized text. This goes beyond the schema's 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 'Semantic search INSIDE a fetched record' — a specific verb and resource. It distinguishes from siblings by contrasting with ask_pipeworx_grounded, and the examples (SEC 10-K, article) clarify the target use case.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also provides pairing guidance with ask_pipeworx_grounded and explains the benefit of saving context. No misleading 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=false and idempotentHint=true, and the description consistently describes a create operation. Beyond annotations, it discloses account requirements, phone verification, SMS caps, and the always-on feed behavior. This adds meaningful context without contradicting the structured hints.

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

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

The description is dense but every sentence earns its place: purpose, return value, prerequisites, supported types with examples, and delivery options are all covered in a compact structure. It is front-loaded with the core purpose and avoids 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 complex tool with three params, nested objects, and five enum types, the description is largely complete. It covers requirements, types, delivery channels, and return value. Minor gaps exist: it omits two enum types (patent_grant, clinical_trial) from the main text, and webhook delivery is only deeply explained in the schema. However, the schema covers these, and overall context remains solid.

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

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

The input schema has detailed type-specific descriptions for all parameters, achieving 100% coverage. The main description adds extra semantic value by giving real-world examples (e.g., items:['5.02'] = officer change, topic:'fed' for polymarket_edge) and explaining feed retrieval. This goes beyond the schema's structural definitions.

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

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

The description clearly states the verb ('Create'), the resource ('proactive monitoring subscription'), and the action's outcome ('Returns the new subscription id'). It distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on the creation of a persistent subscription with live-data event streams.

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 concrete guidance on when to use the tool (creating subscriptions) and prerequisites (Pipeworx OAuth account, verified phone for SMS). It also differentiates from pull-based alternatives ('pull via recent_alerts or GET registry.pipeworx.io/alerts.json') and notes limitations (10/day SMS cap). It does not explicitly name alternative tools but gives sufficient 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, openWorld, idempotent, and non-destructive behavior. The description adds valuable context about the return shape (category-bucketed example questions with exact tool/argument shapes), the live catalog source, and the no-args vs. topic-focused modes, going beyond what annotations alone provide.

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

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

The description is relatively long but every sentence earns its place: it lists example user intents, describes the return categories, explains the argument modes, and gives usage priority. The information is front-loaded with example queries, and the structure makes it scannable despite the length.

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

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

Even though there is no output schema, the description clearly explains what is returned (category-bucketed example questions with exact tool/argument shapes). It covers the main usage modes, the optional topic parameter, and the intended context. Minor details like error behavior or response size are omitted, but they are not essential for a read-only suggestion tool.

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

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

The schema already documents the optional topic parameter with 100% coverage, and the description reinforces its meaning by giving concrete examples ('finance', 'pharma', 'betting') and clarifying the omit-for-full-spread behavior. This adds meaningful semantic detail beyond the raw schema.

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

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

The description clearly states this is the onboarding entry point that returns category-bucketed example questions with exact tool + argument shapes, distinguishing it from sibling tools like ask_pipeworx and discover_tools. The verb 'suggest' plus the resource 'questions' makes the function's 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 explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides guidance on when to pass a topic versus omit it. It does not explicitly list when-not-to-use scenarios or name alternative tools for comparison, but the use-first directive and topic-filtering instructions offer strong practical 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 include idempotentHint=true and destructiveHint=false. The description adds significant behavioral context beyond annotations: 'Ownership is enforced — you can only cancel your own subscriptions' and 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This fully explains safety and side effects, with no contradiction to annotations.

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

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

The description is three short, front-loaded sentences. Each sentence earns its place: purpose, ownership rule, and deactivation behavior. No redundant or low-value content.

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

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

For a simple one-parameter tool with no output schema, the description is complete. It covers the operation, constraints (ownership), consequences (deactivation not deletion), and ties to a related tool (recent_alerts) for historical events. There are 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 input schema provides 100% coverage for the single parameter, including type, format (uuid), and origin ('returned by subscribe'). The description adds no extra meaning about the id parameter beyond referencing it as 'by id', 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 'Cancel a subscription by id' – a specific verb and resource, with the method (by id) and scope (subscription). This distinguishes it from sibling tools like subscribe and list_subscriptions, and further clarifies the behavior as deactivation rather than deletion.

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

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

The description provides context by noting ownership enforcement and that deactivated subscriptions keep historical events available via recent_alerts, implying when this tool is appropriate. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a perfect 5.

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

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

Beyond annotations (readOnly, openWorld, idempotent), description discloses the two-pipeline routing, return fields, and crucially distinguishes could_not_verify from unsupported, warning that could_not_verify is not evidence. This is valuable behavioral context not captured in annotations.

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

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

Though longer than the benchmark example, every sentence is dense with purpose, usage, return value, and edge-case guidance. It is front-loaded with trigger phrases and the core definition, and the 'IMPORTANT for callers' section is essential.

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 fully specifies the verdict vocabulary, return payload, pipeline selection, error semantics, and efficiency rationale. Since no output schema exists, this is necessary and sufficient for an agent to invoke and interpret results correctly.

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

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

Schema already covers both params; description adds meaning: tolerance_pct range, override behavior, default implication (capped at 5), and examples for claim. It also explains the effect on verdict grading, going well beyond the schema descriptions.

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

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

Description opens with trigger phrases, states it is 'natural-language claim verification against authoritative sources,' and names the exact verdict types. It clearly distinguishes from siblings by focusing on fact-checking claims versus general querying.

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 whenever the agent needs to check whether something a user said is factually correct' and differentiates between SEC/XBRL fast path for company-financial claims vs grounded pipeline for all other claims. It notes the tool replaces 4–6 sequential calls, but does not name alternative sibling tools for when not to use it.

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