Ai Feeds

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

Annotations already declare read-only, idempotent, non-destructive. Description adds critical details: default model (Workers AI Llama-3.3-70b free), optional Anthropic via BYO key with direct billing, and per-model result schema. This informs users about cost and external calls.

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

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

Two sentences, front-loaded purpose, no redundant words. Efficiently packs default behavior, cost, output structure, and use cases.

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

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

Despite no output schema, description supplies return shape ({score, confidence, signals, raw_response}) and combined view. With 4 params and 1 required, this is comprehensive for selecting and invoking the 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 100% of parameters. Description adds semantic value by explaining default model behavior and _apiKey cost implications, which are not in the schema. This pushes it beyond 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?

Clearly states the tool probes LLMs for knowledge about an entity and produces a 0-100 visibility score per model. Differentiates from siblings like ask_pipeworx (Q&A) and scan_competitor_ai_presence (competitor-focused) by its scoring and multi-model approach.

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

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

Provides explicit use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Does not explicitly name alternatives or exclusions, but context is clear enough to infer when to use it.

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

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

The description adds substantial behavioral context beyond the annotations: it reveals the tool routes to a large ecosystem of sources, fills arguments automatically, returns citation URIs, and works on every tier with one fast call. The annotations already declare read-only and idempotent behavior, so the description builds on that with operational details. It does not mention failure modes or error handling, but the added context is valuable.

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

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

The description is long but front-loaded with the critical 'PREFER OVER WEB SEARCH' directive and organizes content into distinct sections: scope, mechanism, triggers, examples, and alternatives. Every sentence contributes to selection or invocation guidance. Though dense, it avoids redundancy and is appropriately sized for a tool with this much behavioral nuance.

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

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

The description covers the tool's purpose, when to use it, alternatives, examples, and even the return format (structured answer with pipeworx:// citation URIs). Given the tool's complexity and the absence of an output schema, this is quite complete. It could mention how to handle unsupported queries or errors, but overall it provides sufficient context for an agent to use the tool effectively.

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

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

The input schema has 100% coverage with descriptions for all parameters (including five aliases for 'question'), so the description does not need to re-explain them. The description does provide example questions that illustrate parameter usage implicitly, but it does not add semantic detail beyond the schema. With high schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: it routes factual questions to the appropriate tool among 5,358 sources, fills arguments, and returns structured answers with citation URIs. It uses specific verbs like 'routes' and 'returns' and explicitly distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research, making its unique purpose unambiguous.

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

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

The description provides explicit guidance on when to use this tool over alternatives: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with named sibling tools (ask_pipeworx_grounded for grounded answers, deep_research for broad multi-part questions). It also lists trigger phrases and concrete examples, giving agents clear decision criteria.

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. The description adds valuable context: beta status, candidate routing improvements, current exact match to ask_pipeworx, and that it is a full working router with no fallback. It does not contradict annotations. Not a perfect 5 because response format is only implied via 'same response shape'.

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 slightly long but every sentence adds value: it explains the beta relationship, current state, usage, and behavior. It is front-loaded with the core purpose. Could be tightened, but not verbose enough to drop to 3.

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 complexity (universal router with 5,358 tools) and lack of output schema, the description covers the tool's role, current equivalence to ask_pipeworx, and experimental nature. It references the response shape via ask_pipeworx, which is sufficient for a sibling context. A 5 would require more details about routing behavior or limitations.

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

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

Input schema covers 100% of parameters with descriptions, so baseline is 3. The description mentions 'same arguments' but adds no extra semantic detail beyond the schema. All parameters are aliases for 'question', which is already clear from 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 is a beta version of ask_pipeworx with the same universal router functionality and explicitly distinguishes it from the stable ask_pipeworx and other siblings by mentioning candidate routing improvements and live testing. The verb 'ask' and resource are implicit in the name but fully clarified.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing', giving a clear usage condition. It does not explicitly list when-not-to-use or alternative tools beyond the stable counterpart, so it loses a point for missing 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?

The description discloses significant behavioral traits beyond annotations: the extra LLM call, the use of 'ONLY what the tool result contains,' and the explicit refusal reasons ('not_in_source', 'no_tool_match', etc.). It also details the success return fields. This adds substantial context without contradicting the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint 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 a concise purpose statement, then efficiently covers mechanism, return format, refusal reasons, usage guidance, and cost tradeoff. Every sentence adds value, and the length 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?

With no output schema provided, the description fully specifies the return object ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and the refusal enum. It also covers usage context, tradeoffs vs. alternative, and behavioral constraints, making it complete for invocation decisions.

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

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

Schema coverage is 100% with all parameters described as aliases for 'question' and question itself described as 'Your question in natural language.' The description adds no parameter-specific semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' clearly stating the tool's function as a grounded answer extractor. It explicitly differentiates itself from ask_pipeworx by explaining the same routing but with extraction constrained to tool results, making it distinct from siblings.

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

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

It provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative tool and when to prefer it: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This gives clear decision rules.

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

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

Despite the annotations already declaring readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral context: resolver contract (market_match_confidence, alternatives, suggestions), low-confidence short-circuit behavior, closed market handling, wide-spread market tradeability flag, resolution-rule risk parsing, and fallback behavior for GDELT 429s. It also warns about potential pitfalls (e.g., flat-50¢ void settlements). No contradiction with annotations.

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

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

The description is a long wall of text (~400 words) with many repetitive examples and details that could be moved to separate documentation. While it is front-loaded with the main purpose and uses uppercase labels for sections, it does not earn every sentence: multiple fan-out examples and classifier lists are redundant. It would benefit from significant trimming.

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, which it does comprehensively: response shapes (result.market, result.analysis, result.evidence), resolver contract, parent_event extractor, news fallback fields, safety statuses, and resolution-rule risk. It also covers edge cases and warnings. This is a complete and self-sufficient description 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?

The input schema already covers all three parameters with descriptive text (market, depth, include_raw) at 100% coverage. The description primarily restates the market parameter (slug/URL/question text) and only adds examples of how the tool uses these parameters, not new semantic meaning. The fan-out examples are about tool behavior, not parameter clarification, so the description does not significantly lift the baseline.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' This includes a specific verb ('research'), a specific resource (Polymarket bet via Pipeworx data), and distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges. It also gives concrete use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z').

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

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

The description provides clear usage context: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains the fan-out behavior and examples of when different classifiers trigger. However, it lacks explicit exclusions or pointers to alternative tools for different scenarios, so it doesn't fully meet the 'when-not' criterion.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return format (paired data + citation URIs). It does not mention rate limits or error cases, but the added details go well beyond the annotations.

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

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

The description is dense but well-organized, front-loaded with common queries, then the essential function, then supporting details. Each sentence contributes unique value; none are redundant with the schema or annotations. Slightly long, but justified by the tool's complexity and the need to explain two entity types and data sources.

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

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

There is no output schema, so the description carries the burden of explaining return values. It covers the return format (paired data, citation URIs), sorting behavior, and data provenance. It omits specifics like error handling or pagination, but for a comparison tool with 2 parameters and clear entity types, the description is largely complete.

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

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

Schema coverage is 100% (both type and values are described in the schema). The description adds meaning by explaining what each type retrieves: type='company' pulls revenue, net income, cash, long-term debt from 10-K; type='drug' pulls FAERS counts, FDA approvals, trial counts. It also gives concrete value examples (["AAPL","MSFT"], ["ozempic","mounjaro"]) and notes the max of 5, enriching the schema definitions.

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

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

The description opens with concrete user query examples ("Compare X and Y", "X vs Y") and immediately states the core function: "side-by-side comparison of 2–5 companies or drugs in ONE parallel call." This is a specific verb+resource pairing that clearly distinguishes it from sibling tools like entity_profile (single-entity lookups) and deep_research (broader research).

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

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

Explicit guidance is provided: "ALWAYS PREFER over sequential single-pack lookups when comparing entities" and "Replaces 8–15 sequential lookups." This tells the agent exactly when to choose this tool over alternatives, and the contrast with sequential lookups is a clear usage boundary.

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 adds rich behavioral detail: requires sign-in, paid tier for 'thorough', never invents answers (gaps[]), performs parallel decomposition, returns contradictions[] for some depths, semantically excerpts large records, and gives expected latency ranges. This substantially exceeds annotation coverage.

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, front-loading the critical account requirement. There is some redundancy (e.g., 'never invented' stated twice, citation details repeated) and the lack of paragraphs/bullets hurts scanability. However, every major sentence adds meaningful context for a complex 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 no output schema, the description thoroughly explains the return packet (verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop field), plus timing, auth, and paid-plan constraints. It covers all essential aspects 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 schema already documents both parameters with detailed descriptions (depth meanings and question guidance). The description adds extra semantic nuance, such as 'depth:"thorough" needs a paid plan', the 'second-hop iteration' behavior for standard/thorough, and the explicit advice that breadth in questions is desirable. This goes beyond the schema's descriptions enough to deserve a 4.

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 the tool performs grounded multi-source research across Pipeworx's 1395 structured data sources, decomposing questions into facets and routing to tools in parallel. It clearly distinguishes itself from ask_pipeworx and open-web search, and specifies it is for broad/multi-part questions.

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

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

Explicitly provides when-to-use (broad/multi-part questions over structured data) and when-not-to-use (single lookups or breaking/current news), naming ask_pipeworx as the alternative in both cases. Also notes account prerequisites and that ask_pipeworx works on every tier if not signed in.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds valuable behavioral context: it returns top-N results with full input schemas and curated examples, and each result is 'ready to call directly, no second schema lookup needed.' This goes beyond annotations and sets accurate expectations 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 appropriately sized and front-loaded with the core purpose. The list of data categories is somewhat long but serves the discovery function well. Each sentence earns its place, and there is no fluff.

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

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

The description fully covers when to use, what it returns (names, descriptions, schemas), and behavior (no second lookup). Annotations provide safety context. Despite lacking an output schema, the description's return-value explanation makes the tool complete enough for an agent to select and invoke.

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

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

Schema coverage is 100% with detailed descriptions for all 6 parameters, including aliases and examples. The description mentions 'top-N' which maps to the limit parameter, but does not add significant meaning beyond the schema. Baseline 3 is appropriate since the schema carries the parameter documentation burden.

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

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

The description opens with a specific verb+resource pair: 'Find tools by describing the data or task.' It clearly distinguishes this as a discovery/meta-tool among siblings by focusing on browsing and searching for tools rather than performing domain-specific actions.

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 need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It also implies a when-not by noting 'not just one answer', indicating alternative tools exist for direct answers.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond this: it details the multi-source fan-out (SEC, XBRL, USPTO, GDELT/GNews, GLEIF), the soft-fail for patents due to API sunset, and the GDELT→GNews fallback. This enhances understanding of the tool's behavior, though it does not mention rate limits or latency.

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 carries significant information: example queries, strategic preference over single-pack lookups, fan-out sources, specific return fields, and input constraints. It is front-loaded with user intents and ends with critical limitations. No redundancy or fluff exists.

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

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

Given the tool's complexity (multi-source aggregation) and lack of an output schema, the description thoroughly documents the return values: cik + company_name, recent_filings (with URIs), fundamentals (LATEST 10-K metrics), patents (with caveat), news (with fallback), and LEI. It also explains input format requirements and alternatives for name lookups, 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 description coverage is 100%, with both parameters ('type' and 'value') fully described in the input schema, including the enum constraint and ticker/CIK format. The tool description adds example values but these are essentially identical to the schema descriptions. Thus, the description adds little beyond the structured schema, warranting the baseline score of 3.

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

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

The description clearly states the tool's function: 'full cross-source profile of a US public company in ONE parallel call.' It uses a specific verb ('profile' implicitly) and resource, and distinguishes from siblings by contrasting with 'chaining single-pack SEC/XBRL/news lookups' and referencing resolve_entity for name-based lookups.

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

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

Explicit usage guidance is provided: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives concrete when-not-to-use by stating 'names not supported (use resolve_entity first if you only have a name).' The example queries further clarify the intended use cases.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable context beyond annotations: 'CF-robust: fetches directly and falls back to a proxy if the source blocks the gateway.' This discloses a specific behavioral trait (proxy fallback) that is not encoded in the annotations, and 'normalize' hints at output processing. No contradiction with annotations.

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

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

The description is three sentences, each with purpose: the first states the core action, the second adds a key technical nuance, and the third gives cross-tool guidance. There is zero wasted wording. It is front-loaded and easy to scan.

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

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

For a tool with no output schema, the description covers the core purpose, usage guidance, and a unique behavioral detail. It does not specify the return format or potential errors, but the combination of annotations and the description is sufficient for an agent to select and invoke the tool correctly. A small gap remains in describing output structure, keeping it from a 5.

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 fully describes all three parameters (url, limit, query) with descriptions and examples, giving 100% coverage. The description does not add significantly to parameter semantics beyond the schema; it only restates that the tool fetches by URL. Per the rubric, a baseline of 3 is appropriate when schema coverage is high.

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

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

The description clearly states the action: 'Fetch and normalize any RSS / Atom / RDF feed by URL.' It uses a specific verb ('fetch') and resource ('feed'), and distinguishes itself from list_feeds by explicitly saying 'Use list_feeds first for curated sources.' This makes the tool's purpose unambiguous and differentiated.

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

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

The description provides explicit usage guidance: 'Use list_feeds first for curated sources' implies that fetch_feed is for arbitrary or non-curated feeds. It also adds a behavioral note about CF-robustness, which helps the agent decide when to use this tool. This satisfies the criterion of explicit alternatives and when-to-use.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description does not need to repeat the destructive nature. While it adds context about clearing sensitive data and pairing, it does not disclose additional behavioral traits (e.g., behavior on missing key) beyond what annotations and schema convey. No contradiction.

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

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

The description is two sentences: the first states the action, the second provides usage scenarios and related tools. Every word earns its place; no redundancy.

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

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

For a simple one-parameter tool with no output schema and clear annotations (destructive, idempotent), the description adequately covers purpose, when to use, and complementary tools. No additional information is necessary for correct invocation.

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

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

The input schema fully describes the 'key' parameter as 'Memory key to delete' with 100% coverage. The description repeats 'by key' but adds no further semantic detail, so the baseline of 3 applies.

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

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

The description clearly states the tool's function: 'Delete a previously stored memory by key.' It specifies a concrete verb (delete), object (memory), and method (by key), distinguishing it from siblings by naming 'remember' and 'recall' as companion tools.

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

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

Provides explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with remember and recall, but does not explicitly state when not to use or name direct alternatives, missing the full 5 criteria.

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 this as read-only, idempotent, and non-destructive, so the bar is lower. The description adds valuable context by stating it fetches the page, extracts key info, and emits a standardized markdown blob, which helps the agent understand the exact process and output format 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 two well-structured sentences followed by a succinct 'Useful for' list. It front-loads the core action, explains the process, and provides use cases with zero wasted words. Every sentence earns its place.

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

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

Despite having no output schema, the description clearly states the output format ('standard llms.txt markdown format', 'single text blob') and its intended placement (site-root/llms.txt). It also covers process and use cases. Given the moderate complexity and strong annotations, the description is complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions 'any URL' and 'max_links' implicitly through 'extracts title/description/key links', but it does not add significant detail beyond the schema's parameter descriptions. It is adequate but not enhanced.

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 ('Generate'), names the exact resource ('llms.txt file'), and explains the process (fetches page, extracts title/description/links, emits markdown). It clearly distinguishes itself from siblings like ai_visibility_check by focusing on producing the actual llms.txt artifact rather than checking visibility.

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

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

The description gives explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), which clearly indicates when to use this tool. It does not mention when not to use it or name alternatives, but the context is clear and sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description additionally reveals the curated nature of feeds and that ids can be passed to read_feed, which adds context beyond the structured 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?

Two sentences, front-loaded with the main action, and no filler. Every sentence adds value, including the cross-reference to read_feed.

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 list tool with no output schema, the description covers the resource, output fields, optional filters, and the natural next step. It is complete for its complexity level.

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 parameters are fully described there. The description merely restates that filtering is possible by category or keyword, adding no new 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 clearly states the tool lists curated AI feeds and specifies the output fields (id, title, category, source). It uses a specific verb ('list') and resource ('feeds'), and distinguishes itself from read_feed by indicating a follow-up action.

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

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

It explicitly mentions optional filters (category, keyword) and provides an alternative: 'Pass an id to read_feed.' This tells the agent when to move to a sibling tool instead, which is strong usage 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, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds behavioral detail beyond annotations by listing the exact fields returned (id, type, params, created_at, last_fired_at, fire_count), which helps the agent anticipate the response. It doesn't contradict any annotation.

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: the first states the purpose, the second lists return fields and usage guidance. Every word earns its place, and the description is front-loaded with the primary action.

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 list operation with one optional parameter and no output schema, the description is fully self-contained. It covers what the tool does, what it returns, and why an agent would use it. Annotations handle the safety aspects, so no further context is needed.

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

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

The input schema has 100% coverage with a clear description for the single boolean parameter include_inactive. The description adds marginal context by mentioning 'active subscriptions' and the idea of cancellation (implying inactive states), but this aligns with the schema and doesn't meaningfully extend it. 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 uses a specific verb-resource combination ('List the caller's active subscriptions') and clearly distinguishes this from sibling tools like subscribe/unsubscribe and list_feeds by focusing on subscriptions specific to the caller. It also previews the returned fields, making the purpose crystal 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 usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to invoke it, but it doesn't explicitly mention alternatives or exclusion scenarios (e.g., when to use list_feeds instead). Thus it falls short of a 5.

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

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

Annotations provide no safety or idempotency hints (all false), so the description carries the transparency burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day') and quota independence ('doesn't count against your tool-call quota'), which are valuable operational details 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 moderately long but every sentence adds value: purpose first, followed by when-to-use, content guidance, and operational constraints. It is tightly structured and front-loaded without redundant fluff.

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

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

For a simple feedback tool with no output schema, the description is fully complete. It covers purpose, usage, message formatting, context guidance, rate limits, and cost implications. The schema already handles parameter details, and the description complements it well.

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 parameters are already well documented. The description adds semantic guidance for the message parameter ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and for context usage, which goes beyond the schema's bare 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 the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb ('tell') and resource ('Pipeworx team'), and categorizes feedback types (bug, feature, data_gap, praise), distinguishing it from the sibling research/retrieval tools.

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

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

Explicitly explains when to use the tool: for bug reports, feature requests, data gaps, or praise. It also provides guidance on what not to do ('don't paste the end-user's prompt') and how to frame feedback, making the use cases and exclusions 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?

Given the annotations already declare readOnlyHint=true and destructiveHint=false, the description adds valuable behavioral context: it notes the data is 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count).' It also discloses caching behavior ('Cached 5min-1h depending on window'), which is beyond the annotations and helps set expectations about freshness. No contradictions with annotations.

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

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

The description is concise and well-structured, front-loading the main result and then using a numbered list for use cases. Every sentence adds value: the data source, PII safety, and caching details are all relevant. It avoids redundancy with the schema and annotations, making it efficient and easy to scan.

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 tool with one optional parameter and no output schema, the description covers all necessary aspects: what it returns, how to interpret windows, use cases, data derivation, and caching. The annotations supply safety guarantees, so no further elaboration is needed. This is a complete and self-sufficient description.

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

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

The input schema covers the single 'window' parameter 100%, including the enum values and descriptions. The description reinforces this by listing the windows and stating 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds interpretive nuance but largely mirrors the schema description, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window.' This is a specific verb+resource ('calls on Pipeworx', 'Returns') and differentiates from siblings by detailing the output (top tools, packs, call volume). The listed use cases further clarify its unique niche, such as confirming canonical tool choices.

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

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

The description provides clear usage contexts: 'Useful for: (1) discovering what data sources are hot for current events, (2) confirming a popular tool is the canonical choice before asking your own question, (3) seeing whether your use case aligns with what most agents need.' It implies when to use without explicitly naming alternatives, but the context distinguishes it from discovery-focused tools. No exclusions are mentioned, but the guidance 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?

Annotations already declare read-only, open-world, idempotent, non-destructive behavior. The description adds significant behavioral context: the partition filter dropping placeholder slugs, the 3pp threshold for signals, the fill check that prices against live CLOB depth, and the warning not to trade if realizable_edge_pp ≤ 0. This goes well beyond the annotations.

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

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

The description is lengthy but every section earns its place: it is front-loaded with the core purpose, then clearly structured into mode explanations, semantic anchor, partition filter, response format, and fill check. The use of labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) makes it easy to parse. No wasted sentences.

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 covers return values (opportunities[] with gap_pp, suggested_trade, reasoning, and partition_check fields). It also covers edge cases like placeholders, low similarity, and the fill check, making the tool's behavior complete for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100% with both event and topic described, but the description adds substantial semantic depth: it explains exactly how event mode walks child markets and computes partition checks, how topic mode searches related events across the platform, and provides concrete examples. This far exceeds the schema's basic definitions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes its functionality from sibling tools by specifying the exact method and provides three invocation modes (no args, event, topic). This is a specific verb+resource+scope.

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

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

The description gives explicit usage guidance for each mode: when to use trending_scan (no args), event (recommended for a specific market), and topic (for cross-event scanning). It also names an alternative tool, polymarket_fill_risk, for custom sizing, providing clear when-to-use and alternative guidance.

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

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

While annotations already declare readOnly/idempotent/non-destructive, the description adds extensive behavioral detail: caching at the KV level keyed on all knobs, diagnostics with funnel counters, placeholder-slug filtering, a 24h-move warning, and the decision to surface but exclude Fed bets due to unreliable signal. This goes far beyond the structured annotations.

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

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

The description is dense but every sentence earns its place. It covers the three model families, response field details, tradeable-edge knobs, top-level response layout, diagnostics, and caching—all organized with clear topic shifts and no redundant wording.

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

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

For a tool with no output schema and 9 parameters, the description is exceptionally complete. It defines the full response structure (by_segment, fed_candidates, _diagnostics), explains why segments may be empty (stale top-N, failed gates, knob drops), and details edge cases like placeholder-heavy partitions being skipped. An agent has everything needed to invoke and interpret results.

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

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

Schema coverage is 100% for all 9 parameters, but the description adds valuable inter-parameter semantics: it groups min_liquidity/max_spread_pp as 'tradeable-edge filters' and explains the min_partition_leg_kelly nuance (parent Kelly is 0 for partition arbs, requiring per-leg filtering). This extra context helps agents reason about knob interactions beyond individual schema descriptions.

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

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

The description clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' with a direct use case ('what should I bet on today'). It distinguishes from siblings by detailing three response segments and model families, making the tool's specific function 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 clear context: 'agents discover opportunities without paging hundreds of markets' and explains when to apply tradeable-edge knobs like min_liquidity to drop thin-book opportunities. However, it does not explicitly compare this tool against sibling tools like polymarket_arbitrage, though the Pipeworx disagreement focus implies the differentiation.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds meaningful behavioral context: snapshots are written on cache-miss so gaps mean nobody scanned, decay is computed on daily closes (not intraday), and history is bounded by TTL. This goes well beyond the annotations.

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

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

The description is long but exceptionally well-structured: a purpose statement, args summary, detailed response schema, and explicit limits. Every sentence carries signal; no filler or redundancy. It is front-loaded with the core question it answers and remains scannable.

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

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

With no output schema, the description fully documents the response structure: tracked[] with fields (edge_pp_net time-series, first_seen, trend, decay_pp_per_day), expired[] with lifespan_days, and snapshot_dates[]. It also covers gaps, TTL, and daily-close semantics, making it 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?

Schema already covers both parameters fully (100% coverage, defaults, enums). The description adds interpretive context by describing days as 'lookback' and window as 'snapshot family', and clarifies that decay is computed on |edge_pp_net| (which is relevant to interpreting outputs). This modestly exceeds schema baseline.

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

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

The description explicitly states its function: 'Edge persistence and decay telemetry' from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. This distinguishes it from sibling polymarket_edges (which likely generates the snapshots) by focusing on time-series persistence rather than current edge values.

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

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

Provides a concrete use case: comparing a fresh wide edge to a 3-week-old one, implying this tool should be used when edge age matters. It also states limits (60-day TTL, snapshot gaps) so users know when data may be incomplete, which implicitly explains when not to rely on it.

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

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

The description goes far beyond the annotations (readOnlyHint, idempotentHint) by detailing the internal mechanics: walks the order-book ladder, computes fill prices and slippage, returns specific fields, and discloses risks like partial basket fills converting an arb into an unhedged directional position. It also names forced_directional_risk, a subtle behavioral outcome. No contradiction with annotations.

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

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

Although dense, the description is structured with clear sections (SINGLE-MARKET, BASKET, USE THIS) and every sentence carries operational weight. The opening line states the core purpose, and subsequent lines detail modes, parameters, outputs, and usage. It is long but not wasteful; the complexity of the tool warrants this level of detail.

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

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

For a complex tool with 4 parameters, no required parameters, and no output schema, the description is remarkably complete. It enumerates all return fields for both modes, explains parameter semantics, and provides risk context. An agent can confidently select and invoke this tool correctly, including understanding edge cases like thin legs and partial basket fills.

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

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

Schema description coverage is 100%, but the description adds significant meaning: size_usd is interpreted differently in single-market ('max spend on buys, target proceeds on sells') vs basket ('settlement notional S — shares per leg'), and side has mode-specific defaults and meanings. These enrich the parameter semantics beyond the schema's dry definitions.

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

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

The description opens with a specific verb+resource statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this tool from siblings like polymarket_arbitrage and polymarket_edges by framing it as a fill-risk validation step, and even names those siblings as sources of signals to validate.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the two modes (single-market vs basket) and when each applies, effectively framing when to use this tool versus the signal-generating siblings.

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

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

With annotations already declaring readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds extensive behavioral context: it explains compatibility_warning triggers, temporal_alignment semantics, and skipped_cross_type/subtype counters. This goes well beyond annotations and gives the agent a thorough understanding of edge cases and output 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 long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. Although verbose, every sentence contributes meaningful detail for a tool with significant caveats, so it earns a 4 rather than a 5.

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

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

With no output schema, the description fully explains return values: leg-by-leg prices, spread, compatibility_warning, temporal_alignment, and skip counters. It provides concrete examples of warning conditions and their meanings, making the tool completely understandable for an agent.

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

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

The schema provides 100% coverage for all three parameters, so the baseline is 3. The description adds value by explaining the override semantics ('Overrides the topic-mapped Kalshi side') and the two-mode interaction, which are not in the schema. This clarifies how parameters relate to each other.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which clearly defines the tool's function with a specific resource and scope. It distinguishes itself from sibling tools like polymarket_arbitrage by emphasizing the cross-venue nature, and details two distinct modes for invocation.

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

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

The description clearly explains when to use each mode (topic shortcuts vs explicit ticker/slug) and warns that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable,' providing realistic expectations. It does not explicitly name alternatives, but the context is clear and actionable.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds useful behavioral detail by specifying the normalized return items (title, link, published, summary) and optional keyword filtering, going beyond the structured 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-loads the core action, and includes the return format and filtering option without any redundancy. Every word earns its place.

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

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

With a simple 3-parameter tool, no output schema, and rich safety annotations, the description adequately covers what the tool does, how to identify the feed, the return shape, and an optional behavior. It is suffficient for an AI agent to select and invoke the tool correctly, though it omits details like the limit parameter which the schema already covers.

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

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

Schema coverage is 100%, with each parameter fully described. The description adds marginal value by mentioning the feed id source and keyword filtering, but these are already present in the schema descriptions. Therefore, the baseline of 3 is appropriate.

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

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

The description clearly states the tool reads a curated AI feed by id, specifying the resource and action. It mentions the source (list_feeds) to obtain the id, but does not explicitly differentiate from sibling tools like fetch_feed, so it falls short of a 5.

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 that the feed id must come from list_feeds, which is a usage prerequisite. It does not explicitly state when to use this tool versus alternatives or any exclusions, 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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context by explaining the scoping to the caller's identifier (anonymous IP, BYO key hash, or account ID) and the dual behavior of retrieving a specific key or listing all keys when the key argument is omitted. It does not contradict annotations.

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

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

The description is compact and front-loaded. The first sentence states the core function, the second provides usage guidance, the third gives scoping context, and the final sentence clarifies sibling relationships. Every sentence contributes meaningful information 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 tool with one optional parameter and no output schema, the description covers the main operations, scoping, and related tools. It does not explicitly mention edge cases like missing keys or return formats, but these are not essential for a recall tool and the annotations cover safety semantics. Slightly incomplete for a fully standalone understanding, but quite good overall.

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

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

The input schema already fully describes the key parameter with 100% coverage, including the omission behavior. The description adds context about what kinds of values are stored (e.g., target ticker, address) but does not add meaning beyond the schema's explanation of the parameter itself. This meets the baseline for high schema coverage.

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

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

The description opens with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This clearly distinguishes the recall operation from its sibling tools remember and forget, which are explicitly named, 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?

Explicit usage context is provided: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also gives direct pairing guidance with siblings ('Pair with remember to save, forget to delete'), leaving no doubt about when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by disclosing the mark_read side effect (flagging events read, affecting future calls). It also mentions the same feed is available publicly via URL, which is extra behavioral context. No contradiction with annotations.

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

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

The description is well-structured, starting with the main purpose, then return details, filtering, mark_read behavior, and alternative access. Each sentence adds value with no fluff. It is appropriately sized 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?

Given no output schema, the description covers return payload details (source, citation_uri, raw event payload) and mentions filtering and mark_read. It does not explicitly cover limit and unread_only, but the schema documents those. The alternative URL adds completeness. Overall, the description provides a solid understanding without being exhaustive.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics beyond the schema: it explains the type filter with an example (sec_8k), clarifies that since is an ISO timestamp, and explains that mark_read:true makes the next call only show newer events. This goes beyond basic parameter descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed and returns recent alerts. It describes the payload contents and filtering options, giving a specific verb+resource. However, it does not explicitly differentiate from sibling tools like fetch_feed or read_feed, though the focus on recent alerts and read-marking provides implicit distinction.

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 by mentioning polling works fine and offering a URL for scripts/dashboards, giving context for when to use this tool interactively. It does not explicitly state when not to use it or name alternative tools, so no clear exclusions are provided.

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 readOnlyHint and idempotentHint annotations, the description discloses fallback behavior (GDELT→GNews when rate-limited or 5xx), the USPTO PatentsView API sunset and soft-fail behavior, and the parallel fan-out to multiple sources. This provides operational context not present in annotations.

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

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

Although long, the description is front-loaded with natural-language examples, then systematically covers sources, fallback, parameters, return format, and the alternative tool. Every sentence conveys necessary information; no waste.

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

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

Despite lacking an output schema, the description specifies the return structure (changes[] grouped by source, total_changes, pipeworx:// URIs), parameter nuances, and external API edge cases (sunset, rate-limit fallback). For a tool of this complexity, the description is highly complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds context about the `since` parameter's accepted formats and the value parameter's ticker/CIK formats, but these are already described in the schema. It does not introduce new parameter semantics beyond what the schema provides.

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

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

The description clearly states the tool's function: a change feed for a company over a time window, with concrete examples of queries it handles ('What's new with X', 'updates on Acme'). It also distinguishes itself from entity_profile, which is a sibling tool, by contrasting dynamic changes with static profile data.

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

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

The description provides explicit usage scenarios (e.g., 'what happened to Z this week/month/quarter') and an explicit alternative: 'Use entity_profile instead when you want the static profile'. This directly guides tool selection relative to at least one sibling.

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

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

Beyond the annotations (idempotentHint=true, destructiveHint=false), the description discloses scoping by agent identifier, persistence differences between authenticated and anonymous sessions, and the key-value storage format. These details meaningfully inform how the tool behaves over time and across sessions.

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 states what it does, the second gives usage context and examples, the third details persistence and companions. 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 two-parameter tool with no output schema, the description fully covers purpose, usage trigger, storage behavior, persistence, and integration with recall/forget. No significant gaps remain.

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

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

Schema coverage is 100% with examples for both key and value. The description adds semantic value by emphasizing the key-value nature, the scoping by identifier, and the types of content to store (findings, preferences, notes), which is not fully captured by the schema alone.

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

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

The description opens with 'Save data the agent will need to reuse later' — a specific verb and resource. It immediately clarifies the tool's action and differentiates from siblings by referencing recall and forget as complementary operations. Concrete examples (ticker, address, preference) make 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?

It provides a clear usage trigger ('Use when you discover something worth carrying forward') and names companion tools (recall for retrieval, forget for deletion). However, it does not explicitly list exclusions or when NOT to use the tool, so it lacks the full 'when-not' guidance required for 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?

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive), the description discloses substantial behavioral context: the cascading internal lookup process ('replaces 2-3 manual lookups'), auto-disambiguation, and the exact return payloads including citation URIs. This gives the agent a clear model of what happens on invocation.

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

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

The description is front-loaded with real user utterances and a crisp purpose statement. It is longer than necessary but every sentence carries useful information, including supported returns and internal behavior. No filler or repetition of annotation 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?

With no output schema, the description takes on full responsibility for explaining return values, and it does so thoroughly for both supported types, including fields, data sources, and citation URIs. It also explains why this tool is useful (replaces multiple lookups), making it contextually complete for an agent.

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

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

The schema already provides 100% parameter coverage with detailed descriptions for both type and value. The description adds useful context such as 'auto-disambiguated' and clarifies how the value parameter maps to each entity type, slightly enhancing understanding 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 resolves a user-spoken name to a canonical/official identifier, using a specific verb and resource. It distinguishes itself from siblings by positioning itself as the prerequisite lookup for other tools ('other tools require as input') and by listing concrete examples like 'ticker 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?

The description gives an explicit when-to-use directive: 'Use FIRST whenever you have a name but need an ID.' It also enumerates supported types and acceptable input formats. However, it does not explicitly mention when not to use it or point to alternative sibling tools (e.g., entity_profile) for cases where an ID is already known.

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 hints. The description adds valuable context: it names the underlying tool (ai_visibility_check), explains that each entity is probed, and describes the return structure ('ranked list with score, confidence, signal density per entity'). This goes beyond the annotations to explain what the tool actually does and what the output looks like.

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

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

The description is three sentences, front-loaded with the main action, and includes a concrete example. No word is wasted; every sentence contributes to understanding the tool's purpose, method, and output.

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

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

The tool has no output schema, but the description explicitly lists the return fields (score, confidence, signal density). It also covers the intended use case, the underlying probe mechanism, and the multi-entity scope. Combined with strong annotations and complete schema descriptions, the context is fully sufficient for an agent to select and invoke the tool correctly.

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

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

The input schema has 100% parameter description coverage, so the baseline is 3. The description does not add much beyond the schema: it mentions 'probes each entity with ai_visibility_check' which clarifies the models parameter's role but the schema already describes all parameters. The 'first entry as subject' nuance is already in the schema, so the description adds minimal semantic value.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It specifies the mechanism (probes with ai_visibility_check), the ranking behavior, and the output (ranked list with score, confidence, signal density). This distinguishes it from generic comparison tools like compare_entities by focusing on AI visibility and referencing a specific underlying tool.

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

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

The description gives a clear use case: 'competitive AI-marketing audits' with an example question. It implies this tool is for multi-entity comparisons and mentions it probes each entity with ai_visibility_check, suggesting the single-entity counterpart. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of full explicit guidance.

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

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

The description adds rich behavioral context beyond annotations: it explains the composite fan-out nature, partial failure handling ('sources_failed will list it if it times out'), and latency expectations ('bundlephobia's first measurement... can take 5-30s'). It also outlines the return structure, compensating for the lack of an output schema.

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 serves a purpose: purpose, use cases, ecosystem scope, behavior, failure resolution, return fields. It is well-organized and avoids fluff, achieving high information density without padding.

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 composite tool with no output schema, the description is remarkably complete: it enumerates the returned summary fields, explains partial failure behavior, specifies ecosystem limits and alternative routes, and covers latency. An agent would have all necessary information to invoke this safely and interpret results.

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

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

The schema covers 100% of parameters with clear descriptions, so baseline is 3. The description adds extra value by noting scoped packages are accepted for 'package' and clarifying the default behavior for 'version' (defaults to latest published version). This exceeds schema-only documentation.

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 purpose: a composite 'should I add this npm package to my project' check that fans out across deps.dev and bundlephobia. It explicitly differentiates from siblings by naming its ecosystem scope (npm) and the exact sources queried, making it distinct from tools like scan_competitor_ai_presence.

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

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

The description gives explicit usage triggers ('Use whenever an agent asks...'), specific example queries, and clear exclusions ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This is a model example of when-to-use and when-not-to-use.

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

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

Adds significant behavioral detail beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging. No contradiction with annotations, which already mark it as read-only and idempotent.

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

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

The description is front-loaded with the core purpose, then efficiently expands with usage guidance, technical details, and a companion tool reference. Every sentence provides useful information without redundancy.

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

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

Despite no output schema, the description explains return format (top-N passages, offsets, scores), technical behavior, limitations (truncation), and usage context. Rich annotations and schema cover the rest, making it complete.

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

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

Schema description coverage is 100% with clear parameter descriptions. The tool description adds minimal extra semantic value beyond examples of queries, so baseline 3 is appropriate.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with specific output details (top-N passages, character offsets, similarity scores). It distinguishes itself from siblings by emphasizing 'INSIDE a fetched record' and pairing with ask_pipeworx_grounded.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt' and provides a companion tool (ask_pipeworx_grounded) for grounding over relevant passages. This gives clear context and 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?

The description contradicts the annotations: annotations declare idempotentHint=true, but the description says 'Returns the new subscription id' for each call, implying each invocation creates a distinct subscription. Since the annotation is false, this is an annotation contradiction.

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

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

The description is dense and well-structured, front-loaded with the primary purpose, then covering requirements, types, and delivery. It is somewhat long but every sentence provides value, so it earns a 4 rather than a 5.

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

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

Given the tool's complexity (nested objects, multiple subscription types, delivery channels, and no output schema), the description is highly complete. It covers auth, return value, delivery details, verification, rate limits, and webhook security, making it self-sufficient for the 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?

Despite the schema having 100% coverage, the description adds significant meaning: it explains the supported types with concrete examples (e.g., 'sec_8k' with items), clarifies the delivery channels (feed, email, sms, webhook), and notes constraints like phone verification and rate caps. This goes beyond what the schema provides.

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

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

The description explicitly states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource, and mentions the return value (new subscription id). It clearly distinguishes from sibling tools like unsubscribe and list_subscriptions.

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

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

The description provides clear context: proactive monitoring, OAuth account requirement, and specific delivery options. However, it does not explicitly state when not to use this tool or name alternative tools, so it is not 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 mark it as read-only/idempotent. The description adds behavioral context by explaining the output structure (category-bucketed example questions with exact tool + argument shape) and noting it draws from a live catalog, which aligns with the openWorldHint. No contradictions.

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

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

The description is a single dense paragraph that front-loads common user queries and clearly explains purpose, invocation, and output. While lengthy, each sentence contributes either usage guidance or behavioral detail; no filler.

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

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

For a read-only tool with one optional parameter and no output schema, the description explains what is returned, how to call it, and when to use it. It also notes the live-catalog nature, making it sufficiently complete for an agent.

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

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

The schema description covers 100% of the single parameter, enumerating valid topics. The description only adds the concept of 'focus' and repeats examples, so it does not meaningfully extend the schema; 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 defines a specific action: returning category-bucketed example questions with matching tool calls. It distinguishes itself from siblings by positioning itself as the 'onboarding entry point' and explicitly naming meta-tools (ask_pipeworx, entity_profile, compare_entities) that the user can learn to call.

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 usage 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...' This states when to use and points to alternatives, making it easy 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?

Annotations already signal non-read-only, non-destructive, and idempotent behavior. The description adds meaningful context: ownership enforcement, row deactivation rather than deletion, and preservation of historical events via recent_alerts. This enriches the annotation profile 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 focused sentences, all informative. The action is stated first, followed by key caveats. No redundant or filler content.

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

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

For a single-parameter mutation tool with no output schema, the description covers the essential behavior: ownership, deactivation semantics, and downstream visibility of historical events. It is complete and 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 coverage is 100% with a clear description of the id parameter ('Subscription id (uuid) returned by subscribe'). The description reiterates 'by id' but adds no new parameter-level meaning, 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 specifies a clear action ('Cancel a subscription by id') on a distinct resource (subscriptions), distinguished from sibling tools like subscribe and list_subscriptions. The ownership note adds precision about scope.

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

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

Provides clear context for when to use the tool (canceling one's own subscription) and describes ownership restrictions. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the two-path routing (SEC EDGAR + XBRL vs. grounded pipeline), the exact verdict types returned, and the performance benefit of replacing 4–6 sequential calls. This adds significant behavioral context beyond the structured 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 packed with useful information—examples, usage, routing, output, and performance—all in a structured flow. Every sentence contributes value, and it remains readable despite 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 read-only tool with no output schema, the description fully covers return values (verdicts), citation behavior, and routing. It is complete enough for an agent to know exactly what to expect and how the tool behaves across different claim types.

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

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

Schema coverage is 100% with detailed descriptions for both parameters (claim and tolerance_pct). The description adds minimal extra insight about tolerance behavior ('exact percent-delta math') but largely relies on the schema, which fully documents defaults and limits. 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 is highly specific: 'natural-language claim verification against authoritative sources' with concrete examples. It clearly distinguishes from sibling tools by focusing on fact-checking and returning verdicts, not general Q&A or research.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing for financial vs. other claims, giving clear context. However, it does not explicitly mention when-not-to-use or name alternative tools, so it slightly misses the top bar.

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