Cbs Nl

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: the default model is free, passing `_apiKey` charges the user directly, and it returns a structured per-model response. This goes beyond the baseline set 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?

At about 60 words, every sentence is purposeful: it begins with the action, covers default and paid model options, describes the return format, and ends with practical use cases. No filler or redundancy.

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

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

The description covers the core functionality, model selection, cost implications, output structure, and use cases. Even without an output schema, it explains the per-model response fields. Minor gaps like confidence interpretation or array constraints remain but are partially handled by the 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%, so parameters are well documented. The description enhances this by explaining the default model, the optional `_apiKey` pass-through to Anthropic, and the cost implication, adding meaning beyond the schema definitions.

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

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

The description clearly states the tool probes one or more LLMs for knowledge about an entity and scores visibility (0-100) per model. It uses a specific verb ('probe') and resource ('LLMs'), but does not explicitly distinguish from sibling tools like scan_competitor_ai_presence.

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

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

The description lists concrete use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains the default vs. paid Anthropic model option, giving clear context for when to use it. However, it does not explicitly provide when-not-to-use guidance or 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 cover read-only, idempotent, open-world, and non-destructive behavior. The description adds meaningful behavioral detail beyond those annotations: it routes across 5,767 tools, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. It does not cover failure/fallback behavior, but the disclosed routing and citation behavior is strong 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 it front-loads 'PREFER OVER WEB SEARCH' and packs actionable content: source domains, examples, sibling routing, and special cases. There is some redundancy in repeatedly stressing web-search avoidance and news routing, so it is not perfectly lean, but it earns its length with useful guidance.

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

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

For a one-required-parameter query router with no output schema, the description gives the agent everything necessary: why this tool exists, when it should be preferred, what question forms are accepted, concrete examples, how it behaves when invoked, and what kind of answer to expect (structured data with citations). No missing context would prevent correct invocation.

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

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

The schema provides 100% coverage for the natural-language question parameter and its aliases, so this is a strong baseline. The description goes further by supplying concrete query patterns like 'current US unemployment rate', 'Apple's latest 10-K', and 'patents Tesla was granted last month', plus trigger phrases such as 'what is' and 'look up', which help an agent format and validate inputs.

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 precise directive: this tool is preferred over web search for factual and current questions needing authoritative structured data with citations. It states the operation clearly: routes the question to the right tool among thousands, fills arguments, and returns a structured answer with stable pipeworx:// citation URIs. It also distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description gives explicit when-to-use triggers ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') and covers when not to use it: use ask_pipeworx_grounded for hallucination-resistant single answers with verbatim evidence, and deep_research for broad/multi-part questions. It also explains how breaking-news requests are already handled by this tool, making the routing decision complete.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context: it is a full working router, falls back to nothing (not a stub), and currently matches the stable version exactly. It also explains the experimental edge nature and that candidates are tested live.

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 moderately sized and information-dense, covering identity, current state, usage, and caveats in a few sentences. It front-loads the key concept (beta of ask_pipeworx) before explaining the experimental details. Slightly verbose but each 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 has one required parameter (question), full schema coverage, and no output schema, the description provides enough context for an agent to call it correctly: it is a working router, identical to ask_pipeworx, and currently matches the stable version. The lack of specifics about what routing does or how output is shaped is mitigated by referencing ask_pipeworx as the canonical sibling.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters. The description adds no parameter-specific detail beyond saying arguments are identical to ask_pipeworx, which is meaningful because it references the sibling, but the baseline 3 is appropriate given the schema already covers semantics.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It distinguishes it from the stable ask_pipeworx by explaining it has experimental routing improvements, but the distinction is subtle since they are currently identical.

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 to use it exactly like ask_pipeworx when you want the newest routing, and explains results are compared against the stable router. It names the sibling (ask_pipeworx) and gives clear guidance on when this beta variant is appropriate, plus what happens if no candidate is active.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the exact success and refusal return shapes, the refusal reason enum, and the grounding constraint that answers are extracted solely from the tool result. This gives the agent accurate expectations for failure modes and output structure, especially valuable with no output schema present.

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 but efficiently organized: purpose first, then mechanism, return/refusal contract, usage guidance, and cost tradeoff. Every sentence adds distinct value, and the key contrast with ask_pipeworx appears early.

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

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

For a complex routing tool with no output schema, the description is complete: it covers what the tool does, how it behaves, what it returns, when to use it, when not to, and the tradeoff versus the sibling. An agent has everything needed to invoke and interpret the result correctly.

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

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

Schema coverage is 100%, so the schema already documents that every parameter is an alias for the natural-language question. The description adds no additional parameter-level meaning, and per the baseline that is acceptable, though it could have noted alias preference or formatting expectations.

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 precise function: a grounded, hallucination-resistant Q&A mode that routes like ask_pipeworx and answers only from the tool result. It explicitly names the sibling ask_pipeworx and distinguishes this mode from it, so an agent can select it without opening the schema.

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

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

Usage criteria are explicit: use when the answer will be quoted, cited, or acted on and facts must not be invented, with concrete examples. It also gives the exclusion rule — prefer ask_pipeworx for casual lookups — and discloses the extra LLM-call cost, making the when-to-use decision unambiguous.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, but the description adds extensive behavioral detail: parallel fan-out, resolver contract with market_match_confidence, low-confidence short-circuiting, closed-market status, wide-spread tradeability flag, cancellation-rule risk parsing, and news fallback fields. This far exceeds what annotations provide and contains no contradiction.

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

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

The description is long but well-structured with uppercase section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY). Each section carries essential contract information; while dense, it is not wasteful. Slightly verbose but appropriate for the tool's complexity.

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

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

For a tool with no output schema and high complexity, the description is remarkably complete: it documents response shapes, resolver confidence levels, parent-event extraction, news fallback behavior, safety short-circuits, and cancellation-rule risk. It even quantifies edge thresholds and explains why to inspect market_match_confidence before relying on analysis.

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 are already informative, but the description enriches semantics with concrete fan-out examples (e.g., BTC bet → coingecko + fred + gdelt+gnews) and explains response-shape consequences of depth and include_raw, such as the ~20KB summarized size versus 50KB-500KB raw payloads. This adds 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 opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes this from siblings like polymarket_arbitrage and polymarket_edges by emphasizing evidence packets and market-vs-model comparison rather than arbitrage or edge discovery.

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

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

Explicit 'Use for' guidance is given ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), and classifier/fan-out examples show when common bet types apply. However, it does not explicitly name alternatives or say when NOT to use this tool, so it stops short of full exclusion guidance.

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

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

Beyond the readOnly and idempotent annotations, the description discloses specific data sources (SEC EDGAR/XBRL, FAERS), data fields (revenue, net income, cash, long-term debt), handling of off-calendar fiscal years (AAPL, NVDA examples), result sorting by primary metric, and citation URI format. This provides rich behavioral context without contradicting any annotations.

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

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

The description is compact despite covering multiple aspects: trigger patterns, scope, preference over alternatives, per-type data details, output format, and efficiency. Each sentence serves a purpose, and the layout front-loads examples and usage intent. No fluff or repetition.

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

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

Given the tool's complexity (two entity types, varied data sources, arrays of 2-5 items), the description covers all essential context: what inputs are needed, what behavior to expect, how results are presented (paired data + citations), and why this tool is preferable. With no output schema, it adequately explains return format and further details.

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

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

Although the input schema already has descriptions for both parameters, the description adds significant meaning: it explains what each type ('company' vs 'drug') returns, what data is pulled for each, and how the values array should be populated (tickers vs drug names). It also clarifies that results are sorted by primary metric, adding context 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 purpose as side-by-side comparison of 2–5 companies or drugs in one parallel call, distinguishing it from sibling tools like entity_profile and ask_pipeworx. It uses specific verbs and resource nouns: 'compare', 'companies or drugs', and mentions the exact output behavior. The trigger phrases ('Compare X and Y', 'X vs Y') make intent detection straightforward.

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: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides clear context with example user intents and alternatives (sequential lookups), and even quantifies the benefit ('Replaces 8–15 sequential lookups'). It also distinguishes between company and drug types, guiding the user on appropriate entity types.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description reveals account and paid-tier requirements, parallel decomposition, explicit gaps[] and contradictions[], hop fields, resolvable citation_uri, semantic excerpting, and expected latency. It even explains the failure mode for topics outside the structured catalog.

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

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

The description is dense and front-loaded with the auth gate and main differentiator, but it is a long single paragraph with some redundancy with the schema's depth field and a few convoluted clauses. It earns most of its length by covering auth, output shape, gaps, citations, and timing, 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?

For a complex research tool with no output schema, this description covers the full contract: required auth, alternatives, scope, parallelism, return packet contents, gap handling, citation resolvability, contradiction scanning, and latency. Nothing an agent needs to decide whether and how to call it is missing.

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

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

Schema description coverage is 100%, and the schema already documents both parameters in detail, including the quick/standard/thorough facet counts and the paid tier. The tool description mostly restates the depth semantics rather than adding new parameter-level meaning, so it stays at the baseline for high schema coverage.

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

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

The description opens with a concrete action: grounded multi-source research across Pipeworx's 1506 structured data sources in one call, and explicitly contrasts itself with open-web search. It names sibling alternatives for disambiguation and provides example question types, making the tool'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?

It gives explicit when-to-use guidance ('Best for broad/multi-part questions over structured data') and explicit when-not-to-use guidance: single lookups and breaking/current-news topics should go to ask_pipeworx. It also conditions usage on authentication, directing signed-out users to ask_pipeworx 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the tool returns codes/labels and that dimension is a sub-endpoint, providing useful behavioral context 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 a single, well-structured sentence that front-loads the action and resource. No unnecessary words or restatements.

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 listing tool with fully described parameters and strong annotations, the description is complete. It states what the tool returns (codes/labels), clarifies the dimension parameter, and references sibling tools for context, making it fully sufficient for 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 baseline is 3. The description adds semantic meaning for the 'dimension' parameter by explaining it is a sub-endpoint named in the table root or table_dimensions, which helps clarify how to fill the parameter correctly.

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

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

The description uses a specific verb ('List') and identifies the resource ('valid codes/labels for one dimension of a table'). It clearly distinguishes from sibling tools like table_dimensions (which lists dimensions) and get_data (which retrieves data) by focusing on a single dimension's values.

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 mentions 'as named in the table root or table_dimensions', implying that users should first identify dimensions via table_dimensions or table root. This provides clear context for when to use this tool, though it does not explicitly exclude alternative tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it discloses that results include 'names, descriptions, and full input schemas (with curated examples)' and that each result is 'ready to call directly, no second schema lookup needed.' This explains the return behavior 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, front-loaded with purpose, then usage, then return details. The domain list is long but serves to clarify valid query topics. There is minimal waste, though the domain enumeration could be slightly tighter; still, it earns strong marks for structure.

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

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

There is no output schema, so the description carries the burden of explaining return values. It does so clearly: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas.' It also covers when to use the tool. With a single required parameter, this description fully equips 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?

Schema description coverage is 100%, with detailed aliases and examples for the query parameter. The description adds some context by listing example domains (SEC filings, FDA drugs, etc.) to illustrate valid queries, but it does not introduce new parameter-level meaning beyond what the schema already provides. Baseline for full coverage is 3.

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

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

The description clearly states the verb and resource: 'Find tools by describing the data or task.' It also enumerates specific data domains and positions the tool as the discovery entry point ('Call this FIRST'), distinguishing it from the many sibling tools. This is specific, unambiguous, and not a tautology.

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

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

The description explicitly tells the agent when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It does not name specific alternative tools or provide explicit exclusions, but the context gives strong guidance.

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

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

The description goes far beyond the readOnly/idempotent annotations, disclosing fan-out sources, source-level failure semantics, expected empty sections for fda_products, soft-fail behavior for patents, and the resolved:false path for private companies. It also explicitly explains that an empty section means 'no data', not a bug.

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 the length is justified by the number of data sources and edge cases it covers. It is front-loaded with example user requests and the key 'one parallel call' value proposition, though it is written as a dense single block rather than structured sections.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It covers accepted inputs, all major returned sections, source fallback behavior, expected empty results, and the private-company failure mode, leaving little for an agent to guess.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful meaning: type values are interchangeable, value can be a ticker, zero-padded CIK, or company name, and names resolve via SEC EDGAR company-name matching. It also covers the private-company response behavior, which is helpful 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 an exact purpose: produce a full cross-source profile of a US public company in one parallel call. It opens with concrete user intents like 'tell me about X' and 'research Acme', and it clearly distinguishes this holistic tool from single-pack SEC/XBRL/news lookups.

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

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

It explicitly says to prefer this tool over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view. However, it does not directly contrast with sibling tools like compare_entities, resolve_entity, or deep_research, so some ambiguity about the boundaries with those alternatives remains.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds context that it clears sensitive data and deletes memories the agent saved, which goes beyond the raw annotations. No contradiction.

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

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

Two sentences, front-loaded with the core action followed by usage guidance and sibling pairing. Every word earns its place 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?

For a simple one-parameter tool with strong annotations, the description covers the purpose, usage context, and related tools. No output schema exists, and none is needed. The description is complete for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100% with the 'key' parameter described as 'Memory key to delete'. The description repeats 'by key' without adding new semantic meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool deletes a previously stored memory by key, which is a specific verb+resource. It distinguishes itself from siblings like remember and recall by defining the delete operation, and the pairing note further clarifies its role.

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

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

Explicitly states when to use: when context is stale, task is done, or clearing sensitive data. Names alternative tools (remember and recall) via 'Pair with', giving clear context for tool selection.

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

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

The description discloses that the tool fetches the page, which is a network operation, and that it outputs a text blob in standard llms.txt markdown format. This goes beyond the annotations by explaining the process and the exact form of the output, providing useful behavioral context for the agent.

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 and front-loaded, stating the core function in the first sentence and then supplying use cases. Every sentence contributes value, with no redundancy or filler.

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

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

For a tool with only two parameters and no output schema, this description is complete: it covers the tool's function, process, output, and typical use cases. It leaves no major gaps for an agent to guess.

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

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

The schema provides 100% coverage of both parameters with clear descriptions, so the description doesn't need to add parameter details. The description's mention of 'extracts title/description/key links' slightly reinforces the url parameter's role but doesn't add significant semantic value beyond the schema.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, explaining the process (fetches, extracts title/description/key links) and the output format. This specific verb and resource make its purpose unmistakable and differentiate it from sibling tools like ai_visibility_check.

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

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

It provides explicit use cases ('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'), giving clear context for when to use it. However, it does not mention alternatives or when not to use it.

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

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

Annotations already indicate a safe read operation (readOnlyHint, idempotentHint, destructiveHint false). The description adds valuable behavioral insight, notably the warning that without $top, responses can be huge. It also clarifies that $select should derive keys from table_dimensions, which aids correct invocation.

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

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

Two sentences, efficiently packed with purpose and key usage guidance. The example filter string is concrete. No filler or redundant 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?

The tool is straightforward, and the description covers core purpose and critical usage tips. No output schema exists, but the description doesn't fully explain return format or pagination beyond $top/$skip hints in the schema. Still, it is sufficient for typical usage and does not leave major 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 covers 100% of parameters with examples, so baseline is 3. The description enhances meaning by explaining how $select relates to table_dimensions keys and by advising $top usage to avoid large responses, adding practical semantics beyond the field names.

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 fetches observations from a table (TypedDataSet), which is a specific verb+resource combination. It distinguishes itself from sibling tools like table_dimensions and table_info by focusing on data retrieval and explicitly mentioning OData query params for selecting and filtering.

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: how to use $select (from table_dimensions keys), $filter (with example), and the recommendation to always set $top. However, it does not explicitly contrast with alternative tools or state when to prefer this over siblings, only referencing table_dimensions for 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by specifying the exact return fields and confirming it lists only active subscriptions by default, which goes 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: the first states the action and return fields, the second provides usage guidance. It is efficient, front-loaded, and contains no redundant information.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers the essential return fields and usage context. It could mention pagination or the structure of 'params', but these are minor gaps given the tool's simplicity and the 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?

The schema fully documents the single optional parameter include_inactive with a default behavior, so the description does not need to repeat it. It adds no extra parameter semantics beyond what the schema already provides, matching the baseline for high schema coverage.

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

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

The description clearly states the tool lists the caller's active subscriptions and enumerates the returned fields (id, type, params, created_at, last_fired_at, fire_count). This distinguishes it from sibling tools like subscribe and unsubscribe by focusing on the read-only listing 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?

The description provides explicit use cases: review current monitoring before adding more subscriptions and find an ID to cancel. It does not explicitly name alternative tools or state when not to use it, but the context is clear and sufficient.

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

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

The annotations offer no safety hints (all false), so the description carries the burden. It discloses key behaviors: returning a claim_token for anonymous submissions, allowing later retrieval of status via claim_token, rate limiting (5/day), cost (free, no quota impact), and the team's daily review cycle. This goes well beyond the minimal disclosure expected and matches the annotations without contradiction.

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

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

The description is moderately long but every sentence provides essential guidance: purpose, use cases, exclusions, formatting, follow-up mechanism, limitations, and roadmap impact. It is front-loaded with the purpose and efficiently delivers critical constraints without 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?

This is a relatively complex tool with 4 parameters, nested objects, and no output schema. The description covers all necessary operational context: when to use, what to include, the claim_token follow-up flow, rate limits, and scope restrictions. It even explains return behavior (claim_token when no account), making it complete for the a given 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?

Input schema has 100% parameter descriptions, so baseline is 3. The description adds value by explaining the overall workflow and how parameters like type and claim_token relate to the feedback flow (e.g., 'pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), which is not evident from the schema alone. This warrants a 4 rather than a 3.

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

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

The description clearly states the purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies different feedback types (bug, feature/data gap, praise) and clearly distinguishes itself from sibling tools by focusing on reporting feedback about Pipeworx tools, not querying data or asking questions.

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

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

Provides explicit when to use (bug, feature, data gap, praise) and when not to use (feedback for tools from other MCP servers), going so far as to direct the user to the correct alternative ('file it with that server instead'). Also explains how to structure feedback and mentions the claim_token workflow for follow-up, leaving no ambiguity about 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?

The description adds meaningful behavioral context beyond the annotations: it states the data is derived from CF analytics-engine, contains no PII, and is cached for 5 minutes to 1 hour depending on the window. It also clarifies the output is just (pack, tool, count), which helps set expectations.

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

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

The description is organized with an engaging lead sentence, a clear return statement, a bulleted use-case list, and a concise caveat about caching and privacy. Every section adds value, and the length is appropriate 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?

With only one optional parameter and no output schema, the description provides sufficient context about the output format ((pack, tool, count)), the aggregation source, and the cache behavior. It also explains why the tool might be useful in common scenarios, making it 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?

The schema already fully documents the single window parameter with a clear description of short vs long windows. The tool description does not add significant semantic nuance beyond mentioning the same options, so a 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 begins with a clear question-format summary of what the tool reports, then explicitly lists the return types (top tools, top packs, total call volume) and the window options. It distinguishes itself from siblings like discover_tools by focusing on current call volume rather than static tool discovery.

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

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

The 'Useful for' section provides three concrete use cases: discovering hot data sources, confirming canonical tools, and checking alignment with other agents' needs. However, it does not explicitly mention when not to use the tool or name alternative tools, so it falls short of a 5.

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

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

Annotations already declare read-only/idempotent, but the description adds substantial behavioral detail: fill check against live CLOB depth, 'realizable_edge_pp ≤ 0 means... do not trade it', placeholder filtering, similarity thresholds, and the response shape (opportunities[], partition_check). No contradictions with annotations.

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

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

The description is long but front-loaded with purpose and uses clear section markers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence provides necessary operational detail for a complex tool; nothing is redundant or fluffy.

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 (opportunities[], gap_pp, suggested_trade, partition_check fields) and edge-case behavior (when to avoid trading, placeholder handling, cross-event modes). It is complete for the tool's complexity.

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

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

Schema descriptions are already solid, but the tool description enriches them with concrete examples ('fed-decision-may-2026'), accepted URL formats, mode-specific behaviors, and dual-parameter semantics (event vs topic). It adds meaning far beyond the schema's 100% coverage baseline.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (trending_scan, event, topic) and differentiates from sibling tools by explicitly directing users to polymarket_fill_risk 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?

It provides explicit when-to-use guidance: 'Call with NO args for a trending_scan... pass event... or topic...' and recommends 'event (recommended for a specific market)' while explaining topic mode's cross-event benefits. It also references polymarket_fill_risk as an alternative for sizing, covering when-not-this-tool.

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

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

Annotations already mark this read-only, open-world, idempotent, and non-destructive, and the description adds substantial behavioral detail: 1h KV caching, edge computed net of slippage, five model families with specific logic, and diagnostic funnel counters. No contradictions with annotations were found.

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

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

The description is long but well-structured with section headers, enumerated model families, and clear top-level/response/diagnostic layout. It front-loads the core purpose and every sentence carries substantive information, though the density makes it less immediately scannable than shorter alternatives.

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

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

For a tool with no output schema and nine tunable parameters, this description is unusually complete: it specifies response segments, per-opportunity fields, filtering knobs, caching behavior, diagnostics, and known limitations like the Fed signal unreliability. Callers have nearly all the context needed to interpret results.

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

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

With 100% schema coverage the baseline is 3, but the description adds significant meaning beyond the schema: it labels min_liquidity/max_spread_pp as 'tradeable-edge knobs,' explains min_partition_leg_kelly's special parent-level Kelly behavior, and clarifies that edge is net of slippage with Kelly capped at 0.25.

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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' which names a specific verb, resource, and the tool's unique differentiator. This clearly distinguishes it from siblings like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description states it is built for 'what should I bet on today' and that agents discover opportunities 'without paging hundreds of markets,' giving clear usage context. It also explains exclusions like Fed bets and why, but it does not explicitly name sibling alternatives or state when not to use 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?

The description goes far beyond the readOnlyHint annotation by detailing the response structure (tracked[], expired[], snapshot_dates[]), explaining the meaning of edge_pp_net sign, and disclosing limits (60-day TTL, snapshot gaps, daily closes). This provides rich behavioral context that annotations alone do not convey. 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 exceptionally well-structured with clear sections (Args, RESPONSE, LIMITS) and every sentence adds meaningful information. It is front-loaded with a straightforward purpose, then logically details inputs, outputs, and limitations. There is zero fluff—just dense, useful specification.

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

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

With no output schema, the description fully compensates by explaining the response format, field-by-field, including edge cases (gaps in snapshots, expired opportunities). It also covers computation methodology and TTL limits. For a telemetry tool of this complexity, nothing essential is omitted.

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 documentation covers 100% of both parameters, including defaults and clamps. The description essentially repeats the same info ('days default 14, max 30; window default 1wk'). While it adds a bit of context about 'snapshot family', the schema already provides sufficient semantics. Baseline 3 is correct.

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 'Edge persistence and decay telemetry' and explicitly answers 'how long has this edge existed and is it shrinking?', making the tool's function unmistakable. It also distinguishes itself from the sibling polymarket_edges tool by clarifying it is built from 'daily polymarket_edges snapshots' rather than serving the raw edge data.

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

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

The description clearly implies when to use it—when assessing edge age and decay rather than just current edge values. It does not explicitly name alternative tools or state 'use X instead', but the context ('a fresh wide edge and a 3-week-old wide edge are different trades') gives practical guidance. Lacks explicit exclusion of alternatives, so a 4 is appropriate.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. The description goes far beyond: explains ladder-walking, returned metrics like vwap_fill_price and slippage_pp, and warns about thin-book un-capturable edges and forced directional risk. No contradictions.

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

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

The description is long but tightly packed: mode breakdown, parameter semantics, output list, and usage context. Every sentence contributes information; no filler. The ALL-CAPS emphasis on critical usage is a deliberate structural choice.

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 dual-mode tool with no output schema, the description enumerates all return values (top_of_book, vwap_fill_price, slippage_pp, verdict; basket: theoretical_sum, capture_ratio, thin_legs[], etc.), explains edge cases, and gives risk guidance. It is an exemplary self-contained description.

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 good descriptions, but the tool description adds crucial interpretation: single-market size_usd means 'max spend on buys, target proceeds on sells', basket size_usd means 'settlement notional S (shares per leg)', and side defaults are mode-dependent. This is meaningful added value.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk and liquidity depth.

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

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

Explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Names the exact sibling contexts and provides rationale (partial fills turn arb into directional risk).

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

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

Annotations already declare read-only, idempotent, open-world behavior, and the description adds substantial non-obvious behavioral context: compatibility_codes semantics, unknown legs never paired, gross vs net spread due to Kalshi fees, temporal_alignment null meaning, skipped counters, and the fact that both modes use the same matcher. 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 heavily structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. Each caveat serves a real disambiguation purpose, though there is minor redundancy around 'EITHER mode' and repeated warning codes.

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 is unusually complete: it names response fields (leg-by-leg prices, top_spreads_pp, compatibility_codes, temporal_alignment, fees_note, skipped_cross_type/subtype), explains every compatibility flag, and clarifies null semantics. An agent has enough context to invoke and interpret the tool correctly.

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

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

Schema coverage is 100% and the schema already provides descriptions and examples for all three parameters, including override behavior. The description reinforces the mode semantics but doesn't add much per-parameter meaning beyond what the schema already states, so the baseline of 3 is appropriate.

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

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

The description opens with a specific resource and action: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It also clearly delineates the two operating modes (`topic` vs explicit `kalshi_event_ticker` + `polymarket_event_slug`), making the tool's scope unambiguous and distinguishing it from sibling tools such as polymarket_arbitrage.

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

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

The description explicitly tells the agent when to use the pre-mapped `topic` shortcut versus explicit custom pairings, and warns that pre-mapped topics often return compatibility_warning and are 'pre-mapped ≠ tradeable.' It doesn't explicitly name sibling tools as alternatives, but the in-tool mode selection and cautionary notes are strong.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description doesn't need to repeat those. It adds useful behavioral context about scoping ('Scoped to your identifier...') and the dual behavior (retrieve a single key vs. listing all keys). This goes beyond what annotations provide, though it could mention edge cases like missing keys.

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

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

The description is two sentences, front-loaded with the core action, and every sentence adds value. It includes examples and scoping details without any redundancy or fluff.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete. It covers the two modes (retrieve and list-all), scoping, and the relationship with sibling tools (remember/forget). Annotations fill in the safety profile, so no critical gaps remain.

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

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

The input schema already fully documents the only parameter 'key' with its description ('Memory key to retrieve (omit to list all keys)'), and schema coverage is 100%. The description repeats the omit-tip but adds no new parameter-level detail beyond the schema, so the baseline is 3.

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

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

The description clearly states the tool's purpose: retrieve a value previously saved via remember, or list all saved keys. It uses a specific verb ('retrieve') and resource (values/keys), and distinguishes itself from siblings by explicitly mentioning remember and forget as complementary 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 when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also provides alternatives by naming remember and forget, and clarifies the scoping to the user's identifier, giving the agent clear guidance on 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?

Description contradicts annotations: readOnlyHint is true, but the description describes mark_read:true flagging events as read, a state-changing operation. This is a clear annotation contradiction (annotation_contradiction: true). The description itself is transparent about the mutation, but the annotation misleads, and per rubric this earns a 1.

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

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

Three sentences, front-loaded with the action, includes key parameters and the HTTP alternative. Every sentence earns its place, with no filler.

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

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

Returns are described (source, citation_uri, raw payload) and filter semantics are covered. No output schema exists, so the description compensates adequately. The stateful mark_read behavior is explained, and the HTTP endpoint provides an external reference. Slight gaps around error handling and rate limits are acceptable for a read tool.

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

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

Schema coverage is 100% so baseline is 3. The description adds semantics for mark_read ('flag returned events read so the next call only shows newer ones') and explains type/since with examples, going beyond the schema descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed, with a specific verb ('Pull') and resource (subscription feed). It distinguishes itself from siblings like recent_changes by focusing on subscription alerts and mentioning the evaluator's persisted feed.

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

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

Provides usage context: 'Polls work fine' and offers an alternative HTTP endpoint for scripts/dashboards. It explains filtering by type/since and the mark_read behavior, but does not explicitly exclude sibling tools; however, enough guidance is given for when to use this tool.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description enriches this with concrete behavioral details: fan-out to specific sources (SEC EDGAR, GDELT→GNews fallback, USPTO), soft-failure behavior for PatentsView, date parsing formats, and the return structure including citation URIs. 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?

Though the description is long, every sentence earns its place: usage examples, source list, fallback logic, date parsing, output summary, and alternative tool. It is front-loaded with intuitive questions and structured with clear separators. No fluff.

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

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

The description is thorough for a complex tool with no output schema. It explains the source fan-out, fallback behavior, output shape (changes[] + total_changes + citation URIs), date formats, and when to use a sibling tool. It even flags a known downstream limitation (USPTO soft-fail).

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add meaningful parameter semantics beyond the schema; it merely repeats the `since` format examples already present in the schema. No new meaning is provided for `type` or `value`.

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

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

The description states a clear verb+resource: "change feed for a company in the last N days/weeks/months" with a wealth of natural-language examples ("What's new with X", "updates on Acme"). It explicitly distinguishes itself from sibling tools by suggesting entity_profile for static profiles.

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

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

The description provides explicit usage context with sample queries and clearly names an alternative: "Use entity_profile instead when you want the static profile ... regardless of window." This gives the agent direct guidance on when to pick this tool over a 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?

The description adds valuable behavioral context beyond annotations: persistence scoping by identifier, 24-hour retention for anonymous sessions, and the key-value storage model. This complements the idempotentHint and readOnlyHint without contradiction.

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

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

The description is concise and front-loaded: purpose, usage, storage behavior, and pairing. Each of the four sentences earns its place, though it is slightly longer than strictly necessary.

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

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

For a simple 2-parameter tool with no output schema, the description covers everything: what it does, when to use it, how storage works, persistence durations, and related tools. The agent has sufficient information to invoke it correctly.

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

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

Schema coverage is 100%, and the description reinforces parameter semantics with practical examples (e.g., key patterns like 'target_ticker', value as 'any text'). This adds meaning beyond the schema, helping the agent understand how to populate both fields.

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 with a specific verb ('Save data') and resource ('key-value pair'). It includes concrete examples of what to store (resolved ticker, target address, user preference) and distinguishes itself from siblings by naming recall and forget as partners.

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

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

It explicitly says 'Use when you discover something worth carrying forward' and provides examples of suitable scenarios. It also specifies complementary tools ('Pair with recall to retrieve later, forget to delete'), giving clear guidance on when to use this tool versus 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, openWorldHint, idempotentHint, and destructiveHint=false, but the description goes far beyond: it explains cascading internal lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, handling of ambiguous matches via figi_candidates, and explicit reporting of unresolved identifiers. No contradictions; it adds rich 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?

Though the description is long, every sentence earns its place: it packs examples, edge cases, source details, and degradation behavior without redundancy. The key directive ('Use FIRST...') is front-loaded, and the structure flows from examples to supported types to caveats. There is no filler.

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

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

For a tool with two types, multiple external sources, and numerous edge cases, the description covers everything an agent needs: input formats, output expectations (identifiers, labels, unresolved), ambiguity handling, and fallback behavior. No output schema exists, but the description gives a clear picture of return values. It is complete for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds substantial semantics. For 'type' it explains the two enum values and their respective identifier sources. For 'value', it gives multiple examples (AAPL, CIK, ISIN, drug names), clarifies the bond input rule, and explains how an ISIN resolves to a legal entity via GLEIF. This is far beyond the schema's one-line 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 is explicit: it resolves a user-spoken name to canonical identifiers, with concrete examples ('What's the ticker for...'), supported types (company, drug), and a clear verb-resource pair. It distinguishes itself by covering multiple identifier types (CIK, LEI, FIGI, RxCUI) and specifying the input format, making it easy to differentiate from sibling tools.

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

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

It explicitly instructs 'Use FIRST whenever you have a name but need an ID', giving priority guidance. It also provides detailed when-to-use and when-not-to-use examples, including the bond-specific warning about passing the issuer exactly as printed and avoiding trailing security-class words. This is actionable and comprehensive.

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 establish read-only/idempotent behavior, so the bar is lower. The description adds valuable context by revealing it internally probes each entity via ai_visibility_check and returns a ranked list with score/confidence/signal density—behavioral detail not present in annotations.

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

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

The description is four sentences, each adding meaningful information: purpose, method, use case, and output. No wasteful filler or repetition of schema 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 read-only comparison tool with full schema coverage and no output schema, the description sufficiently explains the use case, internal mechanism, and expected output fields. It gives an agent enough to select and invoke the tool correctly.

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

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

All 4 parameters are already fully documented in the schema (100% coverage), so the baseline is 3. The description's mention of probing each entity and ranking aligns with the entities parameter but doesn't add syntax or format details beyond the schema.

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

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

The description immediately states the verb 'Compare' and the resource 'AI visibility across multiple entities,' and further details the probe-and-rank behavior, clearly distinguishing it from the single-entity ai_visibility_check and generic compare_entities 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 clearly frames this for competitive AI-marketing audits with a concrete example question ('does Claude know about us as well as our competitors?'), and implies that ai_visibility_check is the building block for a single entity. However, it doesn't explicitly contrast with alternatives like compare_entities or specify when not to use it.

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

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

Goes well beyond the annotations by disclosing the fan-out across two external services, the 5-30s latency for first bundlephobia measurement, the graceful degradation via sources_failed, and the exact return content. Annotations (readOnly, idempotent, openWorld) are consistent with the described behavior, and the description adds valuable operational 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?

While a single dense paragraph, it is well-structured: purpose first, then return summary, then ecosystem scope, then failure behavior. Every sentence adds distinct information without redundancy, and the most important decision-relevant info (when to use) is front-loaded.

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

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

Given there is no output schema, the description fully accounts for return values by enumerating the summary block fields, per-advisory details, links, and alternative versions. It also covers the ecosystem boundary and partial failure mode, giving the agent all necessary context to interpret results and make fallback decisions.

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

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

The input schema already fully describes both parameters (package as npm package name, version as specific or default to latest), and description coverage is 100%. The description adds marginal context by framing the package check in the composite flow, but does not significantly extend parameter semantics beyond what the schema provides.

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

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

The description starts with a specific, action-oriented purpose: 'Composite ... check in ONE call' and names the exact resources (deps.dev and bundlephobia) and the question it answers ('is X safe / popular / small'). It clearly distinguishes itself from the listed siblings, none of which perform npm dependency scans.

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

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

Explicitly states when to use ('Use whenever an agent asks...'), and gives a concrete alternative rule ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). Also covers operational expectations with partial failure behavior, so an agent knows how to handle degraded results.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable behavioral specifics: matching is against title only, and table ids ending in 'eng'/'ENG' indicate English labels. This goes beyond annotations without contradicting them.

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

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

Three concise sentences, each with purpose: action+scope, return fields, and language identifier logic. No filler, front-loaded with the primary purpose.

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

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

The tool has only 3 parameters, no output schema, and no nested objects. The description explains what it returns (table id, title, period, language) and key behavioral constraints (keyword matched against title, language suffix rule), which is sufficient for agent use.

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 each parameter has a description. The description's note about language ids slightly reinforces english_only, but schema already says 'id ends in "eng"'. No new parameter syntax or semantics are added, so baseline 3 applies.

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

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

The description clearly states the tool's action ('Find CBS StatLine datasets by keyword') and specifies the matched field (title). It also lists what is returned (table id, title, period, language), which distinguishes it from sibling tools like get_data or table_info that operate on known datasets.

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: use this tool to search datasets by keyword. It does not explicitly mention alternatives or when-not-to-use, but the purpose is unambiguous enough for an agent to select it appropriately among siblings. No exclusions are noted.

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 and idempotentHint, so the description's added behavioral details are a bonus: it discloses the embedding architecture (BGE-base-en + cosine), the windowing (500-char overlapping), and the 200K char truncation behavior with flagging. This goes well beyond the structured annotations and provides actionable expectations for the agent.

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 length-appropriate and front-loaded with the core action. It moves from what the tool does, to when to use it, to how it pairs with a sibling, to technical performance details. Every sentence adds useful information without unnecessary fluff or repetition.

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

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

Even without an output schema, the description fully explains return values (top-N passages with character offsets and similarity scores), the use case for verification, algorithmic details, and input limits. The pairing with ask_pipeworx_grounded also places the tool within a broader workflow, making the description self-sufficient for an agent deciding when and how to invoke it.

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

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

Schema covers all 3 parameters at 100%, so the baseline is 3. The description adds non-redundant value by giving concrete examples for the query parameter and clarifying that the text parameter accepts fetched documents like SEC filings or articles. It also explains the truncation/flagging behavior for oversized text, which slightly extends the schema's 'max ~200K chars' hint.

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

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

The description clearly states the tool performs semantic search inside a provided document ('Semantic search INSIDE a fetched record'). It distinguishes itself from siblings by emphasizing the input is already-fetched text and by explicitly pairing with ask_pipeworx_grounded, making the tool's unique role obvious.

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?

Gives explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt.' It also provides a concrete workflow alternative: fetch with the gateway, then ground over relevant passages via ask_pipeworx_grounded. This clearly contrasts with alternatives and explains the intended usage context.

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

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

Annotations already indicate readOnly=false and idempotent=true; the description adds substantive behavioral context, including the need for a Pipeworx OAuth account, the always-on feed, SMS phone verification and daily cap, and channel-specific constraints. This is beyond what the annotations provide, with 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 dense but well-structured, front-loading the primary action and then methodically covering types and delivery channels. Each sentence contributes meaning, though the length is substantial due to the variety of subscription types and delivery options.

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

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

Given the tool's complexity (multiple types, nested delivery object, no output schema), the description covers auth requirements, return value, supported types, examples, and delivery channels. Minor gaps remain (e.g., webhook details are only in schema, no explicit error/duplicate behavior), but the overall context is strong.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by providing concrete examples for type-specific params (e.g., sec_8k items:['5.02'] = officer change, polymarket_edge topic:'fed') and explaining delivery semantics with email/SMS examples, enhancing 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 clearly states the tool's function: 'Create a proactive monitoring subscription to a live-data event stream' and explicitly mentions the return value ('Returns the new subscription id'). This distinguishes it from sibling tools like list_subscriptions and unsubscribe, which manage existing subscriptions.

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

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

The description provides clear context for when to use the tool (to subscribe to supported event types) and notes prerequisites (OAuth account, verified phone for SMS). However, it does not explicitly name alternative tools for listing or canceling subscriptions, so it falls short of full exclusion/alternative 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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds value by disclosing what the output looks like (category-bucketed example questions, exact tool + argument shape, drawn from live catalog) and that calling with no arguments gives the full spread. 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 a single lengthy paragraph but every sentence contributes: it lists example queries, explains the output, mentions the tool+argument shape, and gives usage instructions. It is front-loaded with the natural language question phrasing. Slightly dense but not wasteful.

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

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

Despite having no output schema, the description fully covers the return value (category-bucketed questions, tool+argument shape). It addresses parameter behavior, usage context, and relationship to meta-tools. Annotations cover safety. For a tool with a single optional parameter and rich descriptive content, it 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 the 'topic' parameter already described. The description adds semantics by explaining the parameter's effect ('to focus') and providing concrete examples ('finance', 'pharma', 'betting'), which goes beyond the schema's enum-like list. This slight addition justifies moving above baseline 3.

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

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

The description clearly states the tool's purpose: the onboarding entry point that returns category-bucketed example questions. It specifies the verb ('suggest'), the resource ('questions'), and the outcome (example questions with exact tool + argument shape). It distinguishes itself from siblings like ask_pipeworx and compare_entities by focusing on generating ideas rather than executing queries.

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 this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning how to call meta-tools. It also explains optional topic filtering. This gives clear when-to-use guidance and names alternatives (meta-tools), though it doesn't explicitly say when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety and side effects. The description adds behavioral context about how to use the returned definitions ($select and $filter), which is useful beyond the structured fields. It does not describe pagination or error behavior, but for a read-only metadata tool this is sufficient.

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

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

The description is two sentences, front-loaded with the core purpose and followed by usage guidance. Every sentence earns its place with no redundant or filler content.

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

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

For a single-parameter read-only tool, the description fully explains what it returns (key, type, unit, decimals) and how it fits into the workflow (before get_data). No output schema exists, but the description compensates by summarizing the return contents. Sibling context is not needed for completeness here.

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 only parameter 'table' is fully described in the schema with an example ('CBS table id, e.g. "37296eng"'), yielding 100% schema description coverage. The tool description does not add additional parameter-specific detail beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the tool provides 'Column/dimension definitions for a table (DataProperties)' and specifies what each field means, its key, type, unit and decimals. It distinguishes itself from siblings like get_data by positioning it as a prerequisite step, 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 explicitly instructs 'Use this before get_data to learn which $select keys and $filter dimensions exist,' providing a clear usage context and workflow guidance. However, it does not explicitly contrast with other metadata tools like dimension_values or table_info, so it lacks a full when-not-to-use statement.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the specific metadata fields returned, which is useful, but it does not describe any other behavioral aspects like error handling, rate limits, or response format beyond the fields listed.

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

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

The description is a single sentence that front-loads the purpose ('Metadata for one table') and lists the output fields compactly. It also includes the required usage example without unnecessary words. Every element earns its place.

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

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

Given the tool's simplicity (one parameter, read-only annotations, no output schema), the description sufficiently covers what the tool does and what it returns. The listed metadata fields set agent expectations, and no additional details are critical for successful invocation.

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

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

The schema has 100% coverage with a description for the 'table' parameter, so the baseline is 3. The description reinforces this with an explicit example ('37296eng'), making the expected input format immediately clear to the agent, 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 that the tool returns metadata for a single table, listing specific metadata fields (title, summary, time period, frequency, update status, description). This distinguishes it from sibling tools like search_tables (which find tables) and get_data (which retrieves data), and it includes a concrete example ID.

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

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

The description gives an instruction to pass a table ID, which implies when to use it (when you need metadata for a known table). However, it does not explicitly compare to alternatives or state exclusions, so the usage guidance is clear but not fully explicit.

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

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

The description discloses important behavioral traits beyond the annotations: ownership enforcement (only cancel your own) and soft-delete semantics (deactivated, not deleted, keeping historical events available). This adds meaningful context to the readOnlyHint=false and destructiveHint=false annotations, explaining why the operation is non-destructive in data retention terms.

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 no redundancy. It front-loads the action, then efficiently covers ownership and data retention behavior, making every sentence purposeful.

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

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

For a simple one-parameter tool, the description covers purpose, ownership restrictions, and the impact on historical data via deactivation. It could mention error handling for unauthorized attempts, but the provided information is sufficient for correct invocation in most cases.

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

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

The input schema already describes the `id` parameter with 100% coverage ("Subscription id (uuid) returned by subscribe"). The description merely repeats "by id" without adding new parameter-specific details, so it does not elevate beyond the schema baseline.

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

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

The description clearly states the action "Cancel a subscription by id" with a specific verb and resource. It distinguishes itself from sibling tools like `subscribe` and `list_subscriptions` by focusing on cancellation, and the ownership constraint further clarifies its 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 clear context on when to use the tool: to cancel a subscription, with the constraint that you can only cancel your own subscriptions. It does not explicitly mention alternatives or exclusions, but the reference to `recent_alerts` for historical events implicitly guides usage after cancellation.

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

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

Despite strong annotations (readOnly, idempotent, openWorld), the description adds critical behavior: the meaning of could_not_verify (check did not happen, not evidence), unsupported (no source covered), and the exact verdict list. Also discloses the dual pipeline (EDGAR fast path vs. grounded). This goes well beyond annotations and prevents misinterpretation.

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

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

The description is long but dense and structured effectively, opening with example queries and then layering routing logic, verdict meanings, and efficiency gains. It could be slightly tighter, but every sentence serves a purpose and the key info is front-loaded.

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

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

Given no output schema, the description fully covers return categories, the difference between unsupported and could_not_verify, and pipeline behavior. It also explains the tool's advantage over sequential calls, making it complete for a complex verification tool.

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

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

Schema coverage is 100%, but the description enriches both parameters: claim gets realistic examples; tolerance_pct gets overrides, default behavior (implied by wording, capped at 5), and a concrete use case (hallucination detection at 1–2). This adds significant 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 this is for natural-language claim verification, with explicit verbs like 'verify', 'fact check', 'confirm or refute'. It distinguishes itself from siblings by focusing on claims about factual truth and mentions replacing 4–6 sequential calls, making its niche unambiguous.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' and explains the routing logic for company-financial vs. other claims. It doesn't explicitly name alternative tools, but the usage context is clear and excludes open-ended Q&A, giving strong practical guidance.

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