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 declare read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds valuable context about routing across thousands of tools, stable citation URIs, and being a fast default entry point. It does not describe error cases or rate limits, but the added context is meaningful 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 comprehensive but somewhat lengthy. It is well-structured, front-loaded with the most important instruction ('PREFER OVER WEB SEARCH'), and every section serves a purpose (domains, examples, alternatives). It could be tightened slightly, but the structure aids readability.

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

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

For a complex, general-purpose question-answering tool with no output schema, the description is quite complete: it specifies return format (structured answer with citation URIs), covers a broad range of domains, provides examples, and gives clear escalation paths. Minor gaps like pagination or error handling are not critical given the tool's design.

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

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

The input schema has 100% description coverage – the main `question` parameter is well documented, and all aliases are clearly marked as aliases. The description adds illustrative examples but no additional parameter-specific semantics, 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 that ask_pipeworx handles factual questions by routing to 5,358 tools across 1,395 verified sources and returning a structured answer with citation URIs. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives for specific scenarios.

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 when-to-use guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions' for the default case. It also gives clear transition rules: use ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions, effectively covering both usage and exclusions.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses the beta nature, live candidate routing experiments, current state of no active candidate, and that results are compared against the stable router for merging decisions. This adds valuable context about experimental behavior and 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 appropriately sized for the complexity, with four sentences each serving a distinct purpose: definition, current status, usage instruction, and fallback reassurance. It is front-loaded with 'Beta version of ask_pipeworx,' and every sentence earns its place without wasted words.

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

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

Given the tool is an open-ended router without an output schema, the description fully covers what it is, how to use it, its relationship to the stable ask_pipeworx, current behavior, and experimental context. Annotations handle safety aspects, and the description sufficiently explains response shape via 'same response shape.'

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

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

The input schema provides 100% coverage with descriptions for the question parameter and all aliases, so the schema carries the parameter meaning. The description adds no new parameter-specific details beyond stating 'same arguments,' which is redundant with the schema and sibling tool reference.

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 ask_pipeworx_beta as a beta variant of ask_pipeworx, explicitly stating it is an identical universal router with the same 5,358 tools, arguments, and response shape. It distinguishes itself from the stable sibling by noting experimental routing improvements and its current identical behavior.

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

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

The description explicitly instructs to 'Use it exactly like ask_pipeworx when you want the newest routing' and contrasts it with the stable router, indicating when to choose this beta variant over alternatives. It also reassures that it is a full working router with no fallback, preventing misuse.

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

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

Beyond the annotations (read-only, idempotent), the description discloses the refusal mechanism with specific refusal reasons, the exact return shape, and the cost implication of an extra LLM call. It also clarifies that answers are extracted 'using ONLY what the tool result contains', which is critical behavioral context. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: the first sentence conveys the core mechanism and success/refusal outputs, the second provides usage guidance and cost tradeoff. It avoids repetition and is well-structured despite its length.

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

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

The tool has no output schema, so the description carries full responsibility for explaining return values, which it does in detail (answer, evidence, confidence, etc.). It also covers the refusal reasoning, the routing to 5,358 tools, and the context for high-stakes use. Given the tool's complexity, the description is remarkably complete.

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

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

Schema description coverage is 100%, with the 'question' parameter and its aliases fully documented in the schema. The description adds no additional parameter-level semantics beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as 'Hallucination-resistant answer mode for high-stakes reads', with a specific verb and resource. It distinguishes itself from the sibling ask_pipeworx by describing the extraction step and refusal behavior, making its unique purpose unambiguous.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on' and for high-stakes domains like financial verdicts, legal claims, and medical lookups. It also names the alternative (ask_pipeworx) and provides a clear tradeoff (extra LLM call vs. casual lookups), fulfilling when/when-not 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/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?

The description significantly expands on annotations by disclosing authentication requirements, latency expectations (15-60s, up to ~90s), and the output packet's structure including gaps[] and contradictions[] arrays, hop field, and citation_uri. It also reveals that findings are never invented and that large records are semantically excerpted. These behavioral traits (pagination, source fidelity, internal decomposition) go far beyond what readOnlyHint/openWorldHint provide, and they align 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 information-dense, covering auth, tool scope, usage guidance, depth semantics, output features, and latency. It is well-structured with clear separations between what the tool does, when to use it, and how depth levels differ. While every sentence contributes value, the length could be trimmed slightly (e.g., repeating 'pipeworx://' citation details) without losing essential guidance, so it's not a perfect 5.

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

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

Given the tool's complexity, no output schema, and no annotations beyond hints, the description fully compensates by explaining return values (verbatim evidence, confidence, source, fetched_at, citation, gaps[]), behavioral limits (not open-web search, may return empty gaps), and operational details (account tiers, latency, depth effects). It also covers edge cases like breaking news and second-hop recovery. This makes the tool's behavior predictable and complete for an agent.

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

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

Schema covers 100% of parameters, but the description enriches both. For 'depth', the description ties each enum value to facet counts, hop behavior, and contradiction scanning (e.g., 'standard' adds gap recovery + contradictions[] scan; 'thorough' adds a full iterative hop), which goes beyond the schema's 'adds a gap-recovery hop' wording. For 'question', the description emphasizes broad/multi-part questions are welcome and that decomposition is the point, matching the schema's natural-language guidance. This adds practical context without needing to restate schema details.

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 grounded multi-source research across Pipeworx's 1395 structured data sources, bundling parallel tool invocations into one call. It explicitly distinguishes itself from sibling tools by noting this is NOT open-web search and contrasting with ask_pipeworx for single lookups and breaking news. Examples of supported question types (e.g., 'compare X and Y's regulatory + financial exposure') further clarify 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?

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and directly names alternatives for other cases ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). Also includes account requirements (sign-in needed, paid plan for thorough) and tells users to use ask_pipeworx if not signed in. This is model usage guidance with exclusions and alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds rich behavioral details: it fans out in parallel, returns specific fields with ordering, includes URI formats, and discloses the USPTO patents API sunset with soft-fall. 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 user intents and a clear summary. Every sentence provides useful information like data sources, fallbacks, or return fields. It is slightly dense but not repetitive, earning a high but not perfect score.

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

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

For a read-only tool with no output schema and moderate complexity, the description fully covers inputs, outputs, data sources, failure modes, and alternatives. It leaves little ambiguity about what the agent should expect, making it complete 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% and the schema already fully documents both parameters, including examples and the unsupported-name constraint. The description repeats this info but adds no new parameter-specific semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description states a specific verb+resource+scope: "full cross-source profile of a US public company in ONE parallel call." It clearly distinguishes from siblings by name-dropping alternatives like resolve_entity and explicitly saying to prefer this over chaining single-pack lookups.

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

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

Explicitly states when to use: "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view." Also gives a clear exclusion: "names not supported (use resolve_entity first if you only have a name)." Example queries help an agent recognize user intent.

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?

Annotations provide no hints, so the description carries the burden. It discloses 'Rate-limited to 5 per identifier per day' and states 'Free; doesn't count against your tool-call quota,' which are important behavioral traits beyond what annotations offer. 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 well-structured: purpose first, then usage triggers, formatting guidance, and operational constraints. Every sentence 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?

With 3 parameters, nested context, and no output schema, the description provides sufficient context for an agent to decide when and how to use the tool. It includes rate limits and quota impact, making it complete for a feedback submission tool.

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

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

The schema already covers all parameters with 100% description coverage, giving a baseline of 3. The description adds value by instructing how to frame the message: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' This enriches the message parameter semantics without repeating schema details.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which clearly states the tool's purpose. It distinguishes itself from sibling tools (which are research/data retrieval) by focusing on feedback submission.

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

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

The description explicitly lists when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides formatting guidance, such as describing issues in terms of Pipeworx tools/packs.

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/non-destructive. The description goes far beyond by detailing response structure, compatibility_warning semantics, temporal_alignment implications, and skipped counters. It also honestly warns that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable,' which is valuable behavioral disclosure.

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

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

The description is lengthy but densely packed, with clear structural markers (TWO MODES, RESPONSE, SAFETY FIELDS). Each sentence adds operational detail; the core purpose is front-loaded in the first sentence. While long, it avoids redundancy and earns its length.

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

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

With no output schema, the description must explain return values, and it does: leg-by-leg prices, spread[].top_spreads_pp, compatibility_warning, temporal_alignment, and skip counters. It also covers edge cases and limitations, making it effectively self-contained for an AI agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining the two modes (topic vs explicit ticker/slug) and how explicit params override topic mapping, which goes beyond schema descriptions. It also gives examples of valid values in 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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' with a specific verb and resource, and distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue comparison. It also details two input modes, making its purpose unambiguous.

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

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

The description explains when to use each mode (topic shortcuts vs explicit pairings) and provides context about when spreads are meaningful ('when the bet shapes are equivalent'). It doesn't explicitly name alternative tools, but the guidance is clear enough for an agent to select this tool for cross-venue spread analysis.

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 indicate read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral detail: it cascades through multiple lookup endpoints, auto-disambiguates input, returns specific fields from specific sources, and emits citation URIs. It does not mention failure or ambiguity edge cases, but the added context is strong.

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

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

The description is well-structured and front-loaded with natural-language trigger examples. Each sentence adds value—covering purpose, usage, supported types, outputs, and internal processing—without redundancy or unnecessary 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?

Despite lacking an output schema, the description explains return fields, data sources, citation URIs, and accepted input variants for both entity types. It gives the agent enough context to select and invoke the tool correctly, though it could mention error handling or ambiguous-name behavior.

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 includes per-parameter descriptions with examples. The description enhances this by mapping each type to its exact output fields, accepted input forms, and the auto-disambiguation behavior, adding value beyond the schema.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers ('What's the ticker for…', 'find the CIK for…'), using a specific verb and resource. It distinguishes itself from siblings by emphasizing that other tools require these identifiers as input, and it details the two supported entity types.

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 trigger phrases and a clear decision rule: 'Use FIRST whenever you have a name but need an ID.' It also explains that the tool replaces 2-3 manual lookups. However, it does not explicitly name alternative tools or list when-not-to-use cases beyond the primary criterion.

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

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

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?

Annotations already declare readOnly/openWorld/idempotent, and the description adds meaningful behavioral context: the dual-path routing, the exact verdict set, the return of verbatim evidence with pipeworx:// citations, and the note that it replaces multiple sequential calls. 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 dense but well-organized: front-loaded with trigger phrases, followed by usage guidance, routing logic, and return value summary. Every sentence earns its place, though it is slightly long; a bit of trimming could improve scannability.

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

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

Given no output schema, the description fully explains return values (verdict types, actual value with citation, reasoning) and covers all parameters and routing behavior. For a tool of this complexity, the description is complete enough for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100%, but the description adds crucial semantics: tolerance_pct overrides the wording-implied tolerance, gives a concrete usage example for hallucination detection (1–2), and states the default behavior (implied by wording, capped at 5). This goes well beyond the schema's generic description.

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

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

The description clearly states the tool's function: natural-language claim verification against authoritative sources, with example user phrasings. It differentiates from sibling tools by focusing on fact-checking and explicitly stating it replaces sequential NL parsing → entity resolution → data lookup → comparison calls.

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 provides routing criteria: company-financial claims use the SEC EDGAR fast path, other claims fall through to the grounded pipeline. This gives clear when-to-use guidance and contrasts with alternative multi-call approaches.

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