dictionary

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

Beyond the readOnly/idempotent annotations, the description discloses cost implications ('BYO key — you pay Anthropic directly'), default model behavior (Workers AI Llama-3.3-70b free), and return structure (per-model {score, confidence, signals, raw_response}). This adds substantive behavioral context.

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

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

Three sentences, each earning its place: function in first, model/API details in second, return/use cases in third. No 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 4 params and annotations, the description covers the tool's purpose, model config, cost, outputs, and use cases. Without an output schema, it still describes the return shape, making it self-sufficient.

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

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

Schema covers all parameters, so baseline is 3. The description adds cross-parameter dependency by explaining that _apiKey is only needed if 'anthropic' is in models, and clarifies the default model for the models parameter. This goes beyond schema descriptions.

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

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

The description opens with a specific verb 'Probe one or more LLMs for what they know about a business / brand / product / topic' and quantifies output as a visibility score (0-100). It clearly differentiates from siblings like ask_pipeworx by focusing on AI visibility auditing rather than general Q&A.

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 ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains model selection with default and BYO key. It doesn't name alternative tools or exclusions, but the use cases give clear context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds genuine behavioral context: it routes internally to the right tool, auto-fills arguments, and returns cited structured answers with stable URIs, without contradicting 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 front-loaded with the most important routing decision and then provides a useful list of domains, trigger phrases, examples, and an alternative. It is a bit long and somewhat redundant between 'PREFER OVER WEB SEARCH', 'Use whenever', and 'START HERE', but the examples and exclusions earn most of their 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?

For a broad, high-complexity tool with no output schema, the description covers input style, scope, return value (structured answer with citations), and a key alternative (deep_research). It does not explicitly differentiate from close siblings like ask_pipeworx_beta or ask_pipeworx_grounded, which is a small but notable gap.

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

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

The schema already documents the single required question parameter and all five aliases with 100% coverage, so the description does not need to add much. It reinforces that the user can ask in natural language and that the tool fills arguments itself, but it adds no deeper parameter formatting or constraint information beyond the schema.

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

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

The description states a specific, distinctive function: a natural-language router that selects among 5,767 tools across 1506 verified sources and returns structured answers with stable pipeworx:// citations. It clearly distinguishes itself from web search and from deep_research for broad multi-part questions, so an agent can tell what this tool is for.

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 opens with 'PREFER OVER WEB SEARCH' and gives explicit trigger phrasing ('what is', 'look up', 'get the latest', 'current') plus concrete examples. It also says to use deep_research for broad/multi-part questions and notes that breaking-news is already routed internally, providing both when-to-use and when-not-to-use guidance.

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

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

Beyond the readOnly, openWorld, idempotent, and non-destructive annotations, the description reveals the experimental nature, the live candidate testing mechanism, and the current production parity. It also confirms there is no fallback—this is a fully functional router, which is important behavioral context.

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

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

The description is a dense paragraph covering purpose, status, usage, and fallback behavior. It front-loads the beta classification and avoids redundancy, though the historical date of the retired candidate is extra detail that could be omitted without losing essential guidance.

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

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

For a tool that is a beta variant of a known router, the description covers all necessary context: identical interface, current parity, experimental routing, usage conditions, and confirmation that it is a complete tool. There is no output schema, but the response shape is stated to match ask_pipeworx, so no critical information is missing.

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

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

Schema coverage is 100% and each parameter is documented as an alias for 'question'. The description adds that arguments are identical to ask_pipeworx, but this does not meaningfully expand on the schema. The baseline of 3 applies since structured schema carries the semantic weight.

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

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

The description clearly states this is the beta version of ask_pipeworx, a universal router with identical tools, arguments, and response shape. It differentiates itself from the stable ask_pipeworx by noting candidate routing improvements and explicitly says it is a full working router, so an agent can understand exactly what it does.

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

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

It explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and notes that results are compared against the stable router. The current state (no active candidate) is disclosed, giving clear guidance on when it is appropriate to invoke.

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

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

Annotations already cover read-only/idempotent safety, but the description adds substantial behavioral detail: the exact success return shape {answer, evidence, confidence, source, fetched_at, refusal_reason:null}, the enumerated refusal reasons, and the 'using ONLY what the tool result contains' guarantee. This goes far beyond what annotations declare.

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 logically sequenced: purpose, mechanism, return contract, usage guidance, and cost trade-off. It is longer than strictly minimal, but every clause contributes useful signal and the main purpose 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?

There is no output schema, so the description properly documents both the success return object and the refusal failure modes. It also explains the routing behavior, the hallucination-resistance guarantee, and when to prefer the cheaper alternative. For a read-only tool with one required parameter, nothing essential is missing.

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

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

Schema coverage is 100% — the schema fully describes the `question` parameter and its aliases. The description adds no parameter-level formatting or constraints beyond the schema, so the baseline 3 applies rather than additional credit.

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

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

The description opens with a specific verb and resource: 'Hallucination-resistant answer mode for high-stakes reads', and then explains exactly how it differs from ask_pipeworx by extracting answers only from tool results. It clearly identifies this as the grounded/evidence-based variant, making it distinguishable from siblings without opening schemas.

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

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

Explicit when-to-use guidance is given: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', followed by concrete domains (financial verdicts, legal claims, medical lookups, public statements). It also names the alternative ('prefer ask_pipeworx for casual lookups') and the cost trade-off ('Costs one extra LLM call').

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 behavior, but the description adds extensive operational detail: parallel fan-out to data sources, response shapes, resolver match confidence levels, safety short-circuits for low-confidence matches, handling of closed/inactive markets, spread warnings, and resolution-rule risks (e.g., refund_50_50). This greatly expands 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 long but well-structured with clear sections (classifiers, fan-out examples, response shapes, resolver contract, safety rules). The first sentence front-loads the purpose, and every section adds necessary detail for a complex tool. It is not overly verbose, though some repetition could be trimmed.

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

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

With no output schema, the description carries the full burden of explaining return values. It thoroughly covers response shapes (result.market, analysis, evidence), status codes (low_confidence_match, market_closed_or_inactive), resolver contract fields, parent-event extraction, news fallback fields, and resolution-rule parsing. Edge cases are explicitly handled.

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 mostly restates what the schema already provides for 'market' (slug, URL, question text). It does not add new meaning for the 'depth' or 'include_raw' parameters, so it does not elevate beyond the baseline.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It also lists explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') that distinguish it from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

The description gives clear usage context with 'Use for...' phrases, but it does not explicitly state when not to use the tool or name alternative tools for comparison. This is clear context without exclusions.

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

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

With annotations already indicating read-only, idempotent, and non-destructive behavior, the description adds substantial context: it pulls data from SEC EDGAR/XBRL and FAERS, handles off-calendar fiscal years, sorts by primary metric, and returns citation URIs. This goes well beyond safety traits and explains the tool's data sources, output format, and sorting behavior.

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

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

The description is longer than typical but each sentence provides critical information: query examples, usage preference, type-specific metrics, data sources, sorting, and return format. It could be slightly tighter (e.g., 'Replaces 8–15 sequential lookups' is promotional), but overall it is well-structured and front-loaded with examples and key guidance.

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

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

The description fully covers the tool's behavior given no output schema: it explains what data is returned (paired data + citation URIs), sorting behavior, supported entity types, and edge cases like off-calendar fiscal years. It also places the tool in context relative to sequential lookups, making it complete for an agent to decide when and how to use it.

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

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

The schema coverage is 100% but the description enriches both parameters: it explains that 'type=company' pulls latest 10-K revenue/net income/cash/debt, and 'type=drug' pulls FAERS adverse-event counts, FDA approval counts, and active trial counts. It also clarifies value formats (tickers/CIKs for companies, names for drugs) and constraints (2–5 items), adding meaning beyond the schema's basic 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 performs side-by-side comparisons of 2–5 companies or drugs in a single parallel call, with specific examples like 'Compare X and Y' and 'X vs Y'. It distinguishes itself from sequential single-pack lookups and defines two distinct entity types (company and drug) with specific metrics, 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 explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a strong usage directive. It also clarifies when to use company vs drug types and mentions edge cases like off-calendar fiscal years. The guidance is sufficient to select this tool over alternatives like entity_profile for comparison tasks.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses key behaviors: parallel decomposition across tools, gap[] reporting for unanswered facets, stable fetchable citations, contradiction scanning for standard/thorough depths, semantic excerpting, and latency expectations. No contradiction with annotations exists.

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

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

The description is information-dense and front-loaded with account requirements and sibling alternatives, but it is a single sprawling paragraph that mixes account info, methodology, output details, depth behavior, caveats, and latency. The content is valuable, but structure could be improved with clearer separation.

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 carries the burden of explaining return values: findings packet contents, evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], and hop fields. It also covers prerequisites, alternatives, latency, and depth behavior. Very complete for an agent to select and invoke correctly.

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

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

Schema coverage is already 100%, but the description adds meaningful nuance: it explains what each depth value means for hops, gap recovery, contradiction scanning, and paid access. It also reinforces that the question parameter should be allowed to be broad and multi-part, which the schema already states.

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

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

The description states a specific action and resource: grounded multi-source research across Pipeworx's 1506 structured data sources in one call. It explicitly contrasts itself with open-web search and distinguishes itself from sibling tools like ask_pipeworx, making it easy for an agent to know what this tool is for.

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

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

It gives explicit routing guidance: use ask_pipeworx when not signed in, for single lookups, or for breaking/current news; use deep_research for broad/multi-part structured-data questions. This is strong when-to-use versus when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds return-value details (meaning, phonetic spelling, example sentences), which provides some behavioral context, but no edge-case behaviors or limitations are disclosed.

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

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

Two concise sentences convey the tool's purpose and output without extraneous information.

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

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

With one well-documented parameter, comprehensive read-only annotations, and an output schema, the description provides sufficient context for an agent to select and invoke the tool correctly.

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

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

The sole parameter 'word' is fully described in the schema with 100% coverage. The description confirms the word is the lookup target but adds no additional parameter semantics beyond what the schema already 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 uses a specific verb 'look up' and identifies the resource as 'a word's definition, pronunciation, part of speech, and usage examples,' which clearly differentiates it from sibling tools like get_synonyms.

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

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

The description implies usage for obtaining word definitions and related linguistic information. It does not explicitly state when to prefer this over get_synonyms or other alternatives, but the context is clear enough for selection.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: that results include 'full input schemas (with curated examples)' and that each result is 'ready to call directly, no second schema lookup needed.' It also implies the tool returns a ranked list ('top-N most relevant'), which is not explicit 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 three sentences, front-loaded with the core purpose. Each sentence adds distinct information: purpose, usage context and scope, return format and placement in the workflow. The list of domains is long but directly informs the agent of the tool's breadth, earning 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?

With no output schema, the description fully explains the return value: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' It also covers when to use (browse/search/discover) and the 'call FIRST' positioning relative to the large sibling set, making it self-sufficient for a discovery tool.

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

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

Schema description coverage is 100%, so the schema fully documents the parameters and aliases. The description adds only a general hint that the query should be a 'natural language description of what you want to do,' which aligns with the schema examples but adds no new syntax or behavioral detail. Baseline 3 is appropriate given complete schema coverage.

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

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

The description opens with 'Find tools by describing the data or task,' a specific verb+resource combination that clearly states the tool's purpose. It further distinguishes itself from sibling tools by positioning it as the discovery entry point, with the phrase 'Call this FIRST when you have many tools available.'

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

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

Explicit usage guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist for' followed by concrete domain examples. It also tells the agent when to prioritize this tool over others: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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

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

Beyond the readOnly, idempotent, openWorld, and non-destructive annotations, the description extensively discloses behavior: source fan-out, soft-fail for the USPTO API, empty sections meaning real 'no data', private-company resolution returning resolved:false with notes, and the interchangeable handling of type values. This is exactly the kind of contextual behavioral disclosure that helps an agent interpret results correctly.

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

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

The description is long, but the tool is genuinely complex with many sources and failure modes to document. It is front-loaded with usage examples and the core one-call value proposition, and the later semicolon-separated return fields are dense but useful. A slightly tighter structure would help, but no sentence feels wasted.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: it enumerates each response section, explains URI formats, notes expected empty cases (FDA small-molecule companies), and covers failure semantics for both sources and private companies. An agent has everything needed to invoke the tool and interpret its result.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds genuine value by explaining that type accepts 'company' or 'ticker' interchangeably regardless of the value shape, that values may be a ticker, zero-padded CIK, or company name, and that names resolve via SEC EDGAR company-name matching. This goes beyond the baseline without being verbose.

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 pair ('full cross-source profile of a US public company') and opens with concrete user-phrase examples that make the intent unmistakable. It also differentiates itself from the generic 'single-pack' lookups by emphasizing the holistic one-call nature, so an agent can tell it apart from sibling tools like resolve_entity or compare_entities.

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

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

The description gives clear context for when to invoke it: when the user asks to 'tell me about', 'research', 'brief me on', or wants a company profile. It also provides an explicit preference rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It stops short of explicitly naming sibling alternatives or stating when not to use the tool, so it earns a 4 rather than 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 disclose destructive behavior (destructiveHint=true) and non-read-only status (readOnlyHint=false). The description adds context about why the destructive action might be taken (clearing stale or sensitive data) and the relationship with remember/recall, going slightly beyond the 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?

The description is three short sentences, front-loaded with the core purpose, followed by usage guidance and a note on related tools. Every sentence earns its place with no redundancy or filler.

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

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

For a simple single-parameter, destructive tool with no output schema, the description is complete: it covers what it does, when to use it, and how it relates to sibling tools. No additional details such as return values are necessary.

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

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

The input schema already provides full parameter documentation with 100% coverage, including the key description 'Memory key to delete'. The description adds no new parameter semantics beyond what the schema offers, so the baseline score of 3 applies.

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

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

The description clearly states the tool's function with a specific verb ('Delete'), resource ('previously stored memory'), and method ('by key'). It distinguishes from siblings like 'remember' and 'recall' by focusing on deletion, and the mention of pairing with those tools 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 lists when to use the tool ('when context is stale, the task is done, or you want to clear sensitive data') and mentions complementary tools ('Pair with remember and recall'), providing clear situational context without needing to exclude alternatives.

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

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

The description discloses the key behavioral steps: fetches the page, extracts elements, and emits a single text blob. This adds useful context beyond the readOnlyHint/idempotentHint annotations, confirming it's a safe, read-only operation that produces a standardized output.

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 tight and front-loaded: first sentence states action and purpose, second explains process, third lists use cases. Every sentence earns its place, and the length is 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?

With no output schema, the description appropriately clarifies the return format ('single text blob ready to drop at site-root/llms.txt'). It covers workflow, purpose, and use cases, making it complete for a tool with only two simple parameters.

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

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

Schema coverage is 100% for both parameters (url and max_links), so the schema does the heavy lifting. The description reinforces that output is a text blob but does not add new meaning beyond what the schema already provides, aligning with the baseline for full 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 a specific action ('Generate a production-ready llms.txt file') with a clear resource (URL) and output (standard llms.txt markdown). It distinguishes itself from sibling tools by focusing on producing the actual file rather than just analyzing 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 'Useful for' section provides concrete use cases (client indexing, personal projects, competitor auditing), giving clear context for when to use the tool. However, it does not explicitly name alternative tools or exclusions, so it falls short of the 'when-not-to-use' guidance.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds minimal behavioral context beyond this, only noting that it 'returns similar words and opposites.' Since output schema exists, this return behavior is likely already documented there.

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 is concise and front-loaded with the primary action ('Find synonyms and antonyms'), followed by the return type and use case. Every part is relevant and no words are wasted.

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

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

For a simple single-parameter tool with a complete schema and output schema present, the description provides sufficient context. It includes the return behavior and a use case ('writing and paraphrasing'). It could be improved by explicitly noting that it works for any word or contrasting with define_word, but these are not necessary for basic completeness.

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% for the single parameter 'word', and the schema description already explains its purpose. The tool description does not add any additional meaning or details 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 states the tool's function with a specific verb and resource: 'Find synonyms and antonyms for any word.' This distinguishes it from the sibling 'define_word' tool, as it explicitly mentions synonyms/antonyms rather than definitions.

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

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

The description provides clear context for when to use the tool: 'useful for writing and paraphrasing.' However, it does not explicitly mention alternatives or when not to use it, which would elevate the score further.

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 destructiveHint false, so the safety profile is clear. The description adds the return field list and the caller-scoped filter, which are useful behavioral details not present in structured data. It doesn't mention pagination or limit behavior, but that's a minor gap for a simple list tool.

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 redundant wording. It front-loads the purpose and then adds return fields and usage guidance, every sentence earning 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?

For a simple list tool with one optional parameter and no output schema, the description is complete: it states what is returned, the scope, and when to use it. No critical information is missing.

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

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

Schema description coverage is 100% for the only parameter (include_inactive), so the schema already explains it. The description adds slightly more context by emphasizing 'active subscriptions' as the default, which aligns with the parameter's default false, but doesn't elaborate on the parameter itself.

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 specifies the verb 'List' and the resource 'the caller's active subscriptions', which distinguishes it from sibling tools like subscribe and unsubscribe. It also clarifies the scope (caller's own) and the type (active only).

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: 'review what you're monitoring before adding more or to find an id to cancel.' This gives clear context for using it with subscribe and unsubscribe, and implies it's not for modifying subscriptions.

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 explains that filing without an account returns a claim_token and that passing it back later lets you 'read whether it was fixed and what changed.' It discloses rate-limiting ('5 per identifier per day'), that the team reads digests daily, and that the tool is free and doesn't count against quota. The only small gap is that the annotations already indicate it's not read-only (readOnlyHint=false) and not idempotent (idempotentHint=false), but the description doesn't explicitly discuss side effects like whether submitting the same message twice creates duplicate feedback entries. Still, the added operational details are substantial.

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, dense paragraph but every sentence adds critical operational information. It front-loads the core purpose ('Tell the Pipeworx team something is broken, missing, or needs to exist') before diving into details. Despite its length, it is well-structured: purpose, when-to-use, exclusions, claim_token flow, SLA/roadmap, rate limit, and cost. 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?

Given the tool's complexity (feedback triage, claim_token flow, multi-server context), the description covers all essential aspects: what it does, when to use it, what not to report here, how to check resolution status, rate limits, and cost implications. The parameters are fully documented in the schema and the description ties them together. No output schema exists, but the description explains what the claim_token returns ('status and, once resolved, what actually changed'), which compensates for the lack of an output schema. The description is fully self-sufficient 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?

Although the schema already provides detailed descriptions for all four parameters (100% coverage), the tool description adds crucial parameter semantics not in the schema: it explains the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), specifies that claim_token should be used 'with no other arguments,' and implicitly clarifies that filing with context is optional but beneficial. The description also clarifies the 'other' type by saying 'anything else' in the schema, but the description's examples make the enum values actionable. The description compensates and extends the schema's parameter docs, earning more than the 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 identifies the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the verb (tell/report), the resource (Pipeworx team), and enumerates the exact types of feedback it accepts (bug, feature, data_gap, praise). It also includes an explicit instruction to only use it for tools served by this connection, which distinguishes it from general feedback tools or reporting to other MCP servers.

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: '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 states when NOT to use it: if the tool came from a different MCP server, file it with that server instead. It even provides a decision heuristic ('Not sure? Pipeworx tool names are the ones this connection lists.').

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: self-aggregating signal from CF analytics-engine, no PII, and caching behavior (5min-1h). This exceeds the minimum but doesn't detail edge cases like rate limits or exact data freshness boundaries.

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

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

The description is well-structured with an opening summary, output statement, bulleted use cases, and technical notes. It is moderately long but each sentence adds distinct value, and the core function is front-loaded. Not as tight as a two-sentence description but appropriately detailed for a multi-purpose tool.

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

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

For a simple read-only analytics tool with one optional parameter and no output schema, the description covers purpose, use cases, data source, privacy, and caching. It gives enough information for an agent to decide when and how to invoke it, and what to expect in return, making it fully contextual.

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 'window' parameter with enum values and descriptions (shorter vs longer windows). The description reiterates the window options and adds caching behavior, but it provides no additional parameter-specific meaning beyond what the schema already states. Baseline 3 applies due to 100% 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 returns top tools, top packs, and total call volume over a window, opening with a specific purpose ('What other AI agents are calling on Pipeworx right now'). This distinguishes it from sibling tools like discover_tools and ask_pipeworx by focusing on aggregate usage trends.

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 explicit use cases (discovering hot data sources, confirming canonical choice, aligning with current demand), giving clear contextual guidance. However, it does not name alternative tools or explicitly state when not to use it, so it falls short of a full 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?

The description adds substantial behavioral context beyond the annotations: no-args default behavior, per-mode output structure, the 3pp deviation threshold, semantic anchor with Jaccard similarity ≥0.30, partition placeholder filtering at >20%, and the fill-check distinction between theoretical and realizable edge with thin_legs[]. It even warns not to trade when realizable_edge_pp ≤ 0, which is critical operational guidance.

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

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

The description is dense but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It front-loads the primary purpose and mode selection, then layers detail. Every sentence contributes actionable information, and the length is justified given the tool's complexity and two distinct modes.

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 specifies the response shape (opportunities[] with fields, partition_check fields), covers edge cases (skipped_low_similarity, placeholder filtering), and explains the fill-check integration with live CLOB depth. It also situates the tool among siblings and ties to polymarket_fill_risk, making it self-contained 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?

Although schema covers 100% of parameters, the description enriches both 'event' and 'topic' with concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), explains that full URLs are accepted for event, and details what each mode does with the parameter. It also adds semantics around argument absence (trending scan), going well 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 an explicit, specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes among three modes (no-args trending scan, event, topic) and contrasts with sibling tools like polymarket_edges and polymarket_fill_risk by focusing solely on arbitrage.

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

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

Provides explicit when-to-use guidance: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It even labels event as 'recommended for a specific market' and explains cross-event mode catches patterns single-event misses. The fill-check section explicitly directs to polymarket_fill_risk for custom sizing, naming an alternative.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds extensive behavioral detail: model families, caching behavior ('Cached 1h at the KV level keyed on all knobs'), diagnostics for empty segments, the 24h-move warning, and the rationale for excluding Fed bets. This far exceeds the annotation baseline and gives agents a strong mental model of runtime behavior.

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

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

The description is a single dense block with no paragraph breaks or bullet points. While every sentence carries technical substance, the sheer length and lack of visual structure make it harder for an agent to parse quickly. It would benefit from section headers or bullet lists, but it is not redundant.

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 9 parameters, no required fields, and no output schema, the description is remarkably complete. It specifies the response top-level keys (by_segment, fed_candidates, _diagnostics), explains each model family's construction, documents tradeable-edge filters, and covers edge cases like placeholder slugs and stale-market diagnostics. Nothing essential is missing.

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

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

Schema coverage is 100%, but the description significantly adds meaning: it explains why min_partition_leg_kelly exists (parent kelly_fraction_half is 0 by design), gives slippage context (Polymarket has zero fees but 20-50bp typical), and provides concrete examples like 'walk the book past breakeven' for min_liquidity. This goes well beyond the schema's field 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 a specific action: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also positions itself for bet discovery and outlines the distinct response segments (model_driven, structural_arbitrage, concentrated_longshot), differentiating it from sibling tools like polymarket_arbitrage by emphasizing opportunity discovery without paging hundreds of markets.

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 with 'Built for "what should I bet on today"' and describes how knobs (min_liquidity, max_spread_pp) refine tradeable edges. However, it never explicitly names sibling alternatives or states 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?

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context beyond annotations: snapshots are written only on cache-miss causing gaps, history depth is bounded by a 60-day TTL, and decay numbers are computed from daily closes, not intraday. This fully discloses operational nuances and limitations.

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 efficiently structured with ARGS, RESPONSE, and LIMITS sections. Every sentence adds critical information about inputs, output shape, and constraints. No filler or redundant phrasing; the density is justified by 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?

Despite having no output schema, the description explicitly defines the response structure (tracked[], expired[], snapshot_dates[]) and key fields (edge_pp_net, trend, decay_pp_per_day, lifespan_days). It also explains limitations (TTL, snapshot gaps, daily closes). Given the tool's complexity and absence of an output schema, this description is remarkably complete.

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

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

Schema coverage is 100%, and both parameters (days, window) have descriptive schema text. The description essentially repeats these (default 14, max 30 for days; default '1wk' for window) without adding new semantic meaning beyond what the schema already provides. The baseline of 3 applies, as the schema does the heavy lifting.

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

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

The description clearly states a specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a concrete question ('how long has this edge existed and is it shrinking?') and differentiates from the sibling tool polymarket_edges, which likely computes current edges. This makes the tool's role distinct and actionable.

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

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

The description implies when to use the tool—when concerned about edge persistence and decay—by noting that 'a fresh wide edge and a 3-week-old wide edge are different trades.' It provides clear context for the trade-off but does not explicitly name alternatives or exclusions. Since sibling tools are listed but not referenced in the description, the guidance is strong 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?

Beyond the read-only/idempotent annotations, the description discloses detailed behavioral traits: it walks the order-book ladder, returns specific fields, computes verdicts, and in basket mode analyzes per-leg fills, thin legs, and forced directional risk. It also warns about the dominant loss mode, providing substantial context.

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

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

The description is long but every sentence earns its place. It is front-loaded with the core purpose, then uses clear markers ('SINGLE-MARKET:', 'BASKET:') to structure the two modes, followed by usage guidance. There is no redundancy or fluff; the density is 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?

Even without an output schema, the description comprehensively enumerates the return values for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, theoretical_sum, capture_ratio, thin_legs). It also explains the risk context and decision support, making the description self-sufficient.

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

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

Although the schema has 100% coverage, the description adds significant meaning beyond it. For instance, it explains how size_usd is interpreted differently in single-market vs. basket mode, clarifies side defaults and behavior in each mode, and specifies what event/market slugs mean. This enriches the schema substantially.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It differentiates from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk, and it details two distinct modes (single-market and basket).

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 is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also names alternatives and explains when the tool is necessary, citing the risk of partial fills and unhedged positions.

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

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

The description goes far beyond the annotations, disclosing that returned matches may still carry compatibility warnings, that legs with 'unknown' metric_type or match_subtype are never paired, that temporal_alignment null means 'could not be computed' rather than aligned, and that spreads are gross of Kalshi fees. This richly characterizes the tool's conservative matching behavior and non-tradeable edge, exceeding what readOnlyHint and idempotentHint alone would convey.

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

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

The description is long but every sentence earns its place, with clear scannable labels like TWO MODES, RESPONSE, SAFETY FIELDS, and Codes. It front-loads the core purpose and then layers critical caveats and return-field semantics without redundancy. For a tool with no output schema and multiple safety fields, this density is justified.

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?

Because there is no output schema, the description must carry the full burden of explaining return values, and it does: spread[], top_spreads_pp, flags[], compatibility_codes[], temporal_alignment, fees_note, skipped_unclassified, and low_confidence_pairs are all described. It also covers edge cases like unknown legs, temporal mismatches, and fee modeling limitations, making the tool safe and correctly invocable without additional documentation.

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

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

The schema already covers all three parameters with descriptions, so the baseline is 3. The description adds meaning by explaining that explicit kalshi_event_ticker and polymarket_event_slug override the topic-mapped sides and that BOTH modes run the identical token-overlap matcher. This clarifies parameter interaction beyond the schema's simple field descriptions.

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

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

The description opens with a specific, verb-like resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It immediately distinguishes the tool's focus from Polymarket-only siblings by naming both venues and the matching concept. It also states the two modes and the exact output the agent can expect, leaving no ambiguity about what the tool does.

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

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

The description gives clear context on when the spread is meaningful ('when the bet shapes are equivalent that delta is a real signal, when they aren't the tool says so') and sets expectations with 'pre-mapped ≠ tradeable.' However, it never names an alternative sibling such as polymarket_arbitrage or explains when to prefer that tool, so the guidance is strong on usage caveats but lacks explicit sibling routing.

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

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

Annotations already provide readOnly and idempotent hints. The description adds meaningful behavioral context: scoping to an identifier (e.g., 'anonymous IP, BYO key hash, or account ID'), dual behavior based on key presence, and the persistence relationship with remember. This goes beyond annotations without contradiction.

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

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

Three sentences, all high-signal: the action, the usage scenario, and the scoping detail. No redundancy or filler; information is front-loaded with the core function first.

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, read-only tool with comprehensive annotations and no output schema, the description covers all essentials: purpose, mode of use, privacy scoping, and integration with sibling tools. The agent can confidently select and invoke this tool correctly.

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

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

Schema coverage is 100% and the single parameter 'key' is described clearly. The description reinforces the semantics with examples ('user's target ticker, an address, prior research notes') and explicitly says omitting the key lists all keys, adding value beyond the raw schema.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This specifies a concrete verb (retrieve/list) and resource (saved memory keys), and distinguishes from siblings by explicitly naming 'remember' and 'forget'.

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

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

Provides explicit usage context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also clarifies when to omit the key for listing and references companion tools (remember/forget), giving clear 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?

The description directly contradicts the annotations. It states that setting mark_read:true flags events as read and affects future calls, which is a state-changing side effect. This conflicts with readOnlyHint:true and also undermines idempotentHint, as repeated calls could behave differently. This is a serious inconsistency.

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 yet densely informative. It starts with a clear action phrase, lists return fields, explains filtering, mark_read, polling, and alternative access—all in one flowing but structured sentence. Every clause earns its place, and there is no 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 description is comprehensive for a read-focused tool with 5 optional parameters and no output schema. It covers the return payload (source, citation_uri, raw event), filtering by type and since, mark_read side effect, polling suitability, and an alternative endpoint. The only missing details (limit, unread_only) are adequately documented in the schema. The tool is fully understandable from the description alone.

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 descriptions (100% coverage), but the description adds valuable semantic detail beyond the schema. It gives a concrete type example ('sec_8k'), clarifies the 'since' parameter as an ISO timestamp, and explains the behavioral effect of mark_read. This adds meaning beyond the raw schema.

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

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

The description clearly states the tool's function with a specific verb ('Pull') and resource ('fired events from your subscription feed'). It distinguishes itself by focusing on recent alerts and mentions return payload details, making it clear what this tool does.

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

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

Provides clear usage context: explains filters, mark_read behavior for incremental reads, notes that polling is fine, and offers an alternative URL for scripts/dashboards. However, it does not explicitly mention when to prefer this over sibling tools, so no exclusions are given.

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 read-only/idempotent annotations, the description discloses fallback behavior (GDELT preferred, GNews on rate-limit/5xx), soft-fail for USPTO due to API sunset, and return structure. This gives the agent realistic expectations about failures and data grouping.

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: example queries, source fallbacks, parameter format, return shape, and sibling distinction. It is front-loaded with natural language examples and remains 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?

With no output schema, the description fully explains the return value ('structured changes[] grouped by source + total_changes count + citation URIs'). It covers all relevant context: sources, fallbacks, parameter syntax, and alternative tool—making it complete for a complex 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 covers all parameters (100% coverage), so baseline is 3. The description adds extra semantic value by explaining `since` relative shorthand with examples and a monitoring tip ('Use "30d" or "1m" for typical monitoring'), which goes 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 defines the tool as a change feed for a company over a time window, listing specific data sources (SEC EDGAR, GDELT/GNews, USPTO). It uses specific verbs and resource scope ('change feed for a company') and explicitly distinguishes from sibling tool entity_profile.

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

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

It provides explicit when-to-use guidance with example queries and a direct alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' This tells the agent exactly when to choose 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?

Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds valuable context beyond annotations: persistence across sessions, 24-hour retention for anonymous sessions, and scope by identifier. This enhances behavioral understanding without contradicting the annotations.

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

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

Three sentences, front-loaded with purpose followed by usage and behavior. Every sentence earns its place: purpose, when to use, persistence behavior, and related tools. No redundancy or filler.

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

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

For a simple 2-parameter tool with no output schema, the description covers all necessary context: purpose, usage triggers, persistence, authentication difference, and relation to recall/forget. Nothing essential is missing.

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

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

Schema covers both parameters with descriptions (coverage 100%). The description only repeats that it's a key-value pair, adding marginal value beyond the schema. Baseline 3 is appropriate since the schema carries the parameter semantics.

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

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

Description clearly states the tool's function: 'Save data the agent will need to reuse later — across this conversation or across sessions.' The verb 'save' with resource 'data' is specific, and the mention of key-value pairs and scoping by identifier distinguishes it from siblings like recall and forget.

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

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

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples. It also names alternatives in context: 'Pair with recall to retrieve later, forget to delete.' However, it lacks an explicit when-not-to-use statement, but the guidance is clear enough.

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

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

Annotations already mark it read-only, open-world, idempotent, and non-destructive. The description adds rich behavioral context: graceful degradation of LEI/FIGI lookup, handling of ambiguous matches via 'figi_candidates', explicit 'unresolved' fields, and internal multi-endpoint cascading. None of this is derivable from annotations alone.

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, with every sentence serving a purpose. It is structured well: usage intent first, supported types with behavior, edge cases, and graceful degradation. It could be slightly tightened, but no sentence is redundant given the complexity of the tool.

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

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

Given only 2 parameters, full schema coverage, and rich annotations, the description thoroughly covers caller-relevant details: supported types, input acceptance, ambiguous resolution behavior, unresolved handling, and fallback mechanisms. It even mentions the internal cascading (replaces 2-3 manual lookups), giving the agent a full operational picture without an output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by detailing the exact format expected in the 'value' parameter (e.g., 'Pass the ENTITY NAME ONLY' with illustrative counterexamples), explaining the type enum's implications, and clarifying how different input forms (ticker, CIK, ISIN) are handled. This adds significant semantic meaning beyond the schema.

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

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

The description states a precise verb ('resolve') and resource (a user-spoken NAME to canonical/official identifiers), lists supported types, and differentiates from siblings by emphasizing it is the first step when you have a name but need an ID. It clearly distinguishes itself from tools like entity_profile or compare_entities by its input-output contract.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID' and provides concrete examples of when to use it. It also gives a negative example (what not to pass for bonds). However, it does not explicitly state when NOT to use this tool (e.g., when you already have the ID and need more details), though that is strongly implied by the phrasing.

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 and idempotent behavior. The description goes beyond this by disclosing the process: 'Probes each entity with ai_visibility_check, ranks by score, surfaces which is most/least recognized' and returns a specific structure ('score, confidence, signal density'). This adds valuable process-level transparency.

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

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

The description is three sentences: purpose, mechanism, and use case. It is front-loaded with the core action, every sentence earns its place, and there is 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 4 params, full schema coverage, and no output schema, the description adequately covers selection and invocation. It explicitly lists the return fields (score, confidence, signal density) and mentions the entities parameter's role, making it complete for an agent to decide and use correctly.

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

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

Schema description coverage is 100%, so all parameters are already well-documented. The description does not add new meaning beyond the schema; it reinforces that entities are compared and probed, but this is already implied. Baseline 3 is appropriate.

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

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

The description opens with 'Compare AI visibility across multiple entities side-by-side', specifying the verb (compare), resource (AI visibility), and scope (multiple entities). It clearly distinguishes from sibling ai_visibility_check by emphasizing the multi-entity comparison and ranking, making the tool's purpose unambiguous.

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

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

The description provides a clear use case: 'Useful for competitive AI-marketing audits' with a concrete example question. It implicitly contrasts with ai_visibility_check by describing the multi-entity approach, but it does not explicitly state when not to use or name 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 read-only, idempotent behavior, but the description adds essential context: bundlephobia's first measurement can take 5-30s, partial failures degrade gracefully with sources_failed reporting, and the tool is NPM-only in v1. This goes beyond annotations to explain latency and failure modes.

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

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

The description is dense and informative, with a clear front-loaded purpose and structured use of dashes and lists. It is slightly longer than strictly necessary but every sentence adds value, making it efficient for a complex composite tool.

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

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

With no output schema, the description fully compensates by listing the summary block fields, per-advisory details, links, alternative versions, and sources_failed behavior. It also covers ecosystem limitations and latency expectations, giving the agent a complete picture of what to expect.

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

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

Schema description coverage is 100%, so both parameters (package, version) are fully documented in the schema. The description adds no new parameter-level details beyond what the schema already says (e.g., version defaults to latest), so the baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: a composite 'should I add this npm package to my project' check combining deps.dev and bundlephobia. It explicitly lists the data sources and the returned summary fields, distinguishing it from sibling tools by noting NPM ecosystem scope and fallback to deps.dev:version for other ecosystems.

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 usage context: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives an alternative path for non-NPM packages (deps.dev:version directly), making when-to-use and when-not-to-use clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, so the bar is lower. Yet the description adds rich behavioral context: it reveals the embedding model (BGE-base-en), the windowing strategy (500-char overlapping windows), the similarity metric (cosine), and the 200K-char cap with truncation flagging. It also states the return format (top-N passages with character offsets and similarity scores), which gives the agent a clear expectation of side effects and output characteristics beyond the annotation hints.

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

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

The description is three sentences, each earning its place: the first defines the mechanism and output, the second explains when to use and the pairing alternative, and the third gives technical implementation details. It is front-loaded with the core purpose and contains no filler or repetition. Every sentence provides distinct value, and the length is 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?

With no output schema, the description does the job of explaining what the agent will receive (top-N passages with offsets and similarity scores). It covers the operational constraints (200K cap, truncation), the technical approach (BGE, cosine, 500-char windows), and the intended use case (cramming large records). It also connects to a sibling tool. For a tool with 3 parameters and no output schema, this is fully 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%, so the schema already documents all three parameters: text, query, and limit. The description adds context by clarifying that text is 'already pulled' and by giving query examples, but it does not add significant meaning beyond what the schema already provides. The 200K cap is also in the schema, and the limit bounds are in the schema. Thus, the description stays at the baseline 3, providing marginal additive 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 precise action: 'Semantic search INSIDE a fetched record,' naming the specific resource (fetched text) and scope (inside that text, not fetching). It differentiates from siblings by explicitly positioning it as a focused search over user-supplied text, and even contrasts with ask_pipeworx_grounded by describing a pairing. The verb 'search' is specific and the examples (SEC 10-K, article) make the purpose immediately clear.

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 a direct use case: 'Use when the record is too big to cram into the prompt.' It also explains how to use it in a workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives both a trigger condition and an integration path, which is more than most tools provide.

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

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

The description goes well beyond the annotations, disclosing that subscriptions require a Pipeworx OAuth account, SMS delivery has a 10/day cap and phone verification, webhook signing secrets are returned only once, and webhooks auto-disable after 10 consecutive failures. These are substantive behavioral traits that an agent needs to know, and they are not present in the annotations.

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

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

The description is lengthy but every sentence carries useful information: purpose, auth, types with examples, and delivery details with caveats. It is front-loaded with the core purpose and uses parentheses/semicolons to compact related information. While dense, it is well-structured and 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?

For a tool with nested objects and no output schema, the description is remarkably complete. It covers the return value, all subscription types and their parameters, delivery options with operational details, and even points to how to consume the always-on feed via recent_alerts or a public URL. This gives an agent everything needed 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?

The schema already provides 100% parameter descriptions, so the baseline is 3. The description adds concrete examples (e.g., items:['5.02'] for officer changes, topic:'fed' for polymarket_edge) and additional constraints (SMS cap, webhook verification details) that enrich the schema's meaning, justifying a score above 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 'Create a proactive monitoring subscription to a live-data event stream' – a specific verb (Create) and resource (subscription) that clearly distinguishes it from sibling tools like list_subscriptions and unsubscribe. It also states the return value (the new subscription id), 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 implies usage for proactive monitoring and provides supported subscription types and delivery channels, but it does not explicitly state when to use this tool vs alternatives (e.g., recent_alerts for on-demand pulls). The auth prerequisite is a constraint but not a comparative guideline, so guidance is present 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 adds meaningful behavioral context beyond the annotations. It discloses that the tool returns category-bucketed examples, drawn from a live catalog of thousands of tools, and explains the parameter behavior (no args for full spread, topic for focus). It does not contradict the readOnly, openWorld, or idempotent hints. Slightly less transparency around edge cases, but the provided context 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 efficient and information-dense, covering purpose, output, usage, and context in about 100 words. It front-loads with example user queries to quickly orient the reader. While slightly dense, every sentence earns its place, and there is no filler.

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

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

Given the lack of an output schema, the description fully explains what the tool returns (category-bucketed example questions with tool+argument shapes) and how to call it. It also covers when to use it and what to expect from the live catalog. For a tool with one optional parameter, this is complete and leaves no significant gaps.

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

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

The schema already fully documents the 'topic' parameter with a list of valid values and the behavior of omitting it for a cross-category spread. The description repeats this with examples (e.g., 'finance', 'pharma', 'betting') but adds no new semantic information. With 100% schema coverage, the description does not need to compensate, so a baseline of 3 is appropriate.

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

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

The description clearly states that this tool is the onboarding entry point for an agent to learn what to ask Pipeworx, returning category-bucketed example questions with exact tool and argument shapes. It distinguishes itself from siblings by explicitly saying 'Use this FIRST' and referencing meta-tools like ask_pipeworx, making its unique role clear.

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: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also mentions specific alternative tools (ask_pipeworx, entity_profile, compare_entities) and how to invoke the tool with or without the topic parameter, covering both context and variations.

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, the description discloses ownership enforcement ('you can only cancel your own subscriptions') and the deactivation behavior ('row is deactivated, not deleted') with the consequence for historical events. This adds meaningful behavioral context beyond the schema and annotations.

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

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

The description is two sentences, front-loaded with the primary action, and each sentence adds necessary detail without redundancy. It is efficient and well-structured.

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

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

For a single-parameter tool with no output schema, the description covers the action, constraints, and outcome, including where historical data can be accessed. It is sufficiently complete for an agent to invoke the tool correctly.

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

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

The schema already describes the 'id' parameter as 'Subscription id (uuid) returned by subscribe.' The description adds no additional parameter semantics beyond what the schema provides, 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 purpose with a specific verb ('Cancel') and resource ('subscription by id'). It distinguishes from sibling tools like subscribe and list_subscriptions by specifying the cancellation action and ownership constraint.

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

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

The description implies the tool should be used when canceling a subscription and provides important contextual details (ownership enforced, deactivation behavior). It does not explicitly name alternatives, but the context is sufficient for an agent to decide.

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

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

Beyond the readOnly/idempotent hints, the description reveals critical behavior: the distinction between 'could_not_verify' (the check did not happen) and 'unsupported' (no source exists), the existence of verification_error{stage,detail}, and the fact that could_not_verify must not be shown as evidence. It also details the return structure with verdict, grounded/structured value, and citation, which is essential for correct agent interpretation.

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

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

The description is dense and front-loaded with user intents and the primary action. While lengthy, each sentence contributes meaningful information: routing logic, verdict semantics, and efficiency benefit. It could be slightly more concise, but the structure supports a complex, multi-behavior tool.

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

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

With no output schema, the description carries the full burden of explaining return values and edge cases. It thoroughly covers the verdict list, the actual value with citation, reasoning, and the special meanings of 'could_not_verify' and 'unsupported'. It also explains internal routing and failure modes, making it fully complete for a 2-parameter 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 provides full descriptions for both parameters (100% coverage). The description adds behavioral nuance by mentioning 'exact percent-delta math' and how tolerance_pct overrides the wording-implied tolerance, clarifying usage for hallucination detection. It also gives real-world examples of claim syntax, enriching understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'natural-language claim verification against authoritative sources.' It provides concrete example intents like 'fact check' and 'verify the claim that…', and specifies the scope (company-financial vs any other claim). It distinguishes itself from generic research tools by explicitly noting it 'Replaces 4–6 sequential calls', making it a unique composite verifier.

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

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

The description gives explicit guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also separates the fast path for company-financial claims from the fallback grounded pipeline. However, it does not name alternative sibling tools or provide explicit 'when-not to use' rules, though it implies it replaces multi-step research.

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