mathjs

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

Annotations cover read-only/idempotent/non-destructive hints; the description adds behavioral nuance by explaining the default model choice (Workers AI Llama-3.3-70b free), the BYO-key arrangement for Anthropic where the user pays directly, and that _apiKey is passed straight through to api.anthropic.com. This exceeds what annotations provide, though it omits details like rate limits or error behavior.

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

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

The description is two sentences, front-loaded with the primary action and key output, followed by specifics. Every clause contributes: default model, cost note, return structure, and use cases—no filler.

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

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

For a tool with no output schema, the description covers the return structure (per-model {score, confidence, signals, raw_response} + combined view) and key parameters. Together with full schema and annotations, this is sufficient for an agent to select and invoke correctly, although interpretation of the score scale is left implicit.

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 each parameter (entity, models, _apiKey, context) already has meaningful descriptions. The tool description adds value by clarifying the default model selection and the cost implication of using the Anthropic key, which complement rather than repeat the schema.

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

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

The description opens with a specific verb ('Probe'), resource ('one or more LLMs'), and output ('score visibility 0-100 per model'), making the tool's function unmistakable. It doesn't explicitly differentiate from siblings like scan_competitor_ai_presence, but the core purpose is clear and distinct from general question-answering tools.

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

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

The description explicitly lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') which provides context for when to invoke. However, it does not contrast with sibling tools or provide exclusion criteria, so usage guidance is clear but not fully positioned against alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context: it routes to 5,621 tools, fills arguments, and returns structured answers with pipeworx:// citation URIs. 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 longer than average but front-loads the key instruction and domains, and most content earns its place with concrete examples. The all-caps emphasis and overlapping examples make it slightly less concise than ideal.

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 one required parameter and no output schema, the description is nearly complete: it states what it does, when to use it, what it returns, and provides domain coverage. It lacks explicit mention of limitations, rate limits, or sibling selection criteria, but overall it gives an agent enough to invoke it correctly.

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

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

The input schema fully documents the aliases and the main 'question' parameter with 100% coverage, so the baseline is 3. The description adds meaningful scope and examples (e.g., unemployment rate, 10-K, clinical trials), helping an agent understand what kinds of natural-language inputs are appropriate.

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

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

The description clearly identifies ask_pipeworx as a general factual/current-data question router that returns cited answers, and lists many domains. However, it does not differentiate it from sibling tools like ask_pipeworx_beta or ask_pipeworx_grounded, so it stops one step 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 gives explicit trigger phrases, explicitly says to prefer it over web search, and includes concrete examples plus a 'START HERE' directive. It does not specify exclusions or when to choose related siblings, so the guidance is strong but not fully complete.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable context beyond that: it is an experimental router with possible candidate improvements enabled live (none currently active), and it 'falls back to nothing — this IS a full working router, just the experimental edge.' This informs the agent that behavior may change and results are compared against the stable router. 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 several sentences but each contributes: beta status, identical behavior, no active candidate, usage guidance, and fallback assertion. It is slightly verbose but not wasteful. The key scoping statement ('currently matches ask_pipeworx exactly') is front-loaded early. Overall well-structured and readable.

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 universal router with no output schema, the description clearly explains how to use it (like ask_pipeworx) and its experimental nature. It references the stable sibling ask_pipeworx for the actual response shape and usage, which is sufficient given that sibling exists and is presumably documented. The description is complete enough for an agent to invoke it correctly without further guesswork, though it leans on ask_pipeworx for return details.

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

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

The input schema covers 100% of parameters, including aliases and the main 'question' field description. The description only says 'same arguments' but doesn't add new semantics beyond what the schema already documents. Since schema coverage is high (100%), this meets the baseline; the description doesn't need to repeat parameter details, and it doesn't offer extra value here.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router with identical capabilities. It specifies the exact relationship to its sibling (same tools, arguments, response shape) and current state (no active candidate, so matches ask_pipeworx exactly), making the purpose unambiguous and distinct from the stable router.

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 states when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes the experimental nature and that results are compared against the stable router. It doesn't list exclusions (e.g., when NOT to use it), but the condition 'when you want the newest routing' provides clear guidance, and the sibling ask_pipeworx is implied as the alternative.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, but the description adds rich behavioral detail: it extracts answers only from tool results, returns an explicit refusal with specific reason codes (not_in_source, no_tool_match, etc.), and outlines the return schema. This goes far beyond the annotations and is crucial for safe 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 dense but well-organized: starts with the core differentiator, explains the routing and extraction process, then covers return format and usage guidance. Each sentence earns its place, though it could be trimmed slightly without losing info. It is front-loaded with the key message.

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 what the tool does, when to use it, the return structure (including refusal reasons), the cost trade-off, and its relationship to the sibling ask_pipeworx. With no output schema, the explicit return shape is essential and provided. For a tool with this complexity, nothing is missing.

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

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

Schema coverage is 100%—all parameters (question and aliases) are described as 'Alias for question.' The description does not add additional meaning beyond the schema because the only parameter is the question itself, which is self-explanatory. No further parameter guidance is possible or needed.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode for high-stakes reads, with explicit contrast to ask_pipeworx. It specifies the verb (answers), the resource (Pipeworx data), and the differentiator (grounded extraction). No ambiguity about what it does.

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

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

Provides explicit when-to-use guidance: use for quoted/cited/acted-on answers where facts must not be invented, and prefer ask_pipeworx for casual lookups. Also states the cost difference (extra LLM call), giving a clear trade-off. This fully covers usage selection.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses numerous behavioral nuances: the low-confidence short-circuit returning status:'low_confidence_match', the closed/dead market path with status:'market_closed_or_inactive', the wide-spread tradeability flag, the cancellation rule parsing, and the GDELT 429 fallback mechanism. It also warns about the 24h-move caveat. This far exceeds what annotations alone provide.

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

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

The description is long but appropriately organized with explicit labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.) and each section addresses a distinct concern for a complex tool. The opening sentence is a clear summary, and the rest provides essential operational detail. It could be trimmed slightly, but the structure earns its length.

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

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

With no output schema, the description fully covers return values: result.market, result.analysis, result.evidence, resolver contract, parent_event, news fields, and statuses. It also covers edge cases like closed markets, cancellation rules, and fallback behavior. For a tool of this complexity, it is remarkably complete – an agent can predict behavior and response structure without ever having called it.

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

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

The schema covers all three parameters with descriptions, so the baseline is 3. The description adds value by explaining the resolver contract for the `market` parameter (slug/URL/question text), the effect of `depth` on fan-out, and the `include_raw` trade-off (response size). It also gives real-world examples that show how the input is interpreted, going beyond the schema's static type 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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' – a specific verb+resource that immediately differentiates it from sibling tools like polymarket_arbitrage or polymarket_edges. It also lists explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and classifiers, leaving no ambiguity about what the tool does.

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

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

The description explicitly states when to use it: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It provides concrete fan-out examples (BTC, Fed, Hormuz, Yankees, hottest-year, NVDA-vs-AAPL) that show how the tool selects data sources. Although it doesn't name sibling tools as alternatives, the distinct use cases and the level of detail make the intended usage unmistakable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral context beyond these: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and the return of paired data with citation URIs. This far exceeds the annotation-only information.

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 adds value: trigger phrases, entity count, preference over alternatives, data sources, fiscal year handling, sorting, and return type. It is front-loaded with the core purpose and contains no filler or redundancy.

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

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

Given the tool's complexity (two entity types with distinct data sources, sorting, citation output) and no output schema, the description covers all essential aspects: what it does, what data it pulls, how results are ordered, and what is returned. It is complete enough for an agent to select and invoke correctly. The absence of an output schema is mitigated by the description's explanation of paired data and citation URIs.

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

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

Although schema coverage is 100%, the description enriches both parameters significantly. For 'type' it explains what data each enum value pulls (company financials vs. drug counts), and for 'values' it provides concrete examples (tickers/CIKs, drug names) and clarifies the 2-5 limit. It also notes the latest 10-K data for companies, which the schema does not convey.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs in one parallel call, with a specific verb ('compare') and resource ('entities'). It distinguishes itself from siblings by covering both companies and drugs and explicitly noting it replaces many sequential 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?

The description gives explicit trigger phrases and states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This provides strong when-to-use guidance. However, it does not explicitly state when NOT to use the tool (e.g., for single-entity lookups or more than 5 entities), though this is implied.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds that it returns a converted value and illustrates supported unit formats, but doesn't disclose edge-case behaviors like error handling or unsupported units.

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 short and front-loaded with the core purpose. It includes somewhat redundant phrases like 'Returns converted value' and 'Use for unit conversions' that could be trimmed, but overall it is efficient and well-structured.

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

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

For a simple conversion tool, the description, schema, annotations, and output schema together provide sufficient context. The examples clarify usage, and the categories set expectations. Missing error handling details are not critical for such a benign operation.

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

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

The schema has 100% description coverage for all three parameters, each with examples. The description adds examples of unit expressions (e.g., 'm to ft', 'degF to degC') but doesn't substantially expand beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool converts units, lists supported categories (length, weight, temperature, volume, time), and provides concrete examples. This makes its purpose unambiguous and distinguishes it from the unrelated sibling tools.

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

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

It explicitly says 'Use for unit conversions' and gives examples of input formats, providing clear context for when to invoke the tool. However, it doesn't name alternatives or state when not to use it, so it lacks exclusions but is still clear.

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

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

Annotations already mark the tool as read-only, open-world, and idempotent, but the description adds substantial behavioral context: it requires sign-in, thorough requires a paid plan, it can take 15-90s, it returns gaps[] rather than inventing answers, produces stable fetchable citations, includes contradictions[] for standard/thorough, and semantically excerpts large records. This far exceeds the minimal bar set by the annotations and is not contradicted by 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 long, but the length is mostly justified given the tool's complexity, no output schema, and multiple behavioral nuances. It is front-loaded with the most operationally important information (account requirement and alternative tool). It loses a point because some sections feel meandering and slightly redundant, and the CURRENT-NEWS guidance could be worded more cleanly.

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 only two parameters and no output schema, the description covers everything an agent needs to select and invoke it correctly: auth requirements, cost differences, alternatives, latency, result shape (findings packet), confidence/source/citation fields, gaps[], contradictions[], and behavior on out-of-scope topics. Nothing critical is missing.

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

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

Schema coverage is 100%, so the parameters are already documented. The description adds genuine semantic value by explaining real-world implications of the depth parameter (number of facets, single-hop vs gap-recovery vs iterative chase, paid tier, latency), and by clarifying that the question parameter is meant for broad/multi-part natural-language questions. This is above the baseline but not a 5 because the description still relies on the schema for the exact enum values and parameter names.

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

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

The description states a specific verb and resource ('Grounded multi-source research across Pipeworx's 1,472 STRUCTURED data sources') and explicitly distinguishes itself from open-web search and from ask_pipeworx. It also communicates the core decomposition/parallel behavior ('Decomposes your question... routes each to... 5,621 tools IN PARALLEL'), so an agent can clearly understand what this tool is for.

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

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

The description gives explicit when-to-use guidance ('Best for broad/multi-part questions over structured data') and explicit exclusions ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx'). It also provides auth/tier guidance ('If you are not signed in, use ask_pipeworx instead') and explains which depth levels are paid.

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. The description adds valuable context: it returns top-N tools with 'names, descriptions, and full input schemas (with curated examples)' and states that 'each result is ready to call directly, no second schema lookup needed.' This goes beyond the safe-read trait to describe the response format and eliminates a potential follow-up step, but it doesn't discuss ranking criteria or rate limits.

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

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

The description is three sentences, front-loaded with the primary action ('Find tools by describing...'). The second sentence is dense but justified, packing a domain list and return-format details. No filler words; it is efficient for the amount of information conveyed.

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

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

Given the tool is a meta-discovery tool with 6 parameters and no output schema, the description adequately explains the return value (tools with schemas ready for direct invocation) and the intended use. It could mention how relevance ranking works or what 'top-N' is based on, but the provided context is sufficient for an agent to invoke it correctly.

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

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

Schema description coverage is 100%: all parameters (query, q, task, limit, search, description) have explicit descriptions and aliases, with examples provided in the schema. The description itself does not add parameter-level meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description opens with 'Find tools by describing the data or task', a specific verb+resource statement. It clarifies the tool's role as a discovery meta-tool and lists concrete domains (SEC filings, FDA drugs, FRED, etc.), which distinguishes it from sibling tools that operate on specific data or perform analysis.

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 direction is given: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly indicates when to use it over other tools and reinforces its place as an initial discovery step.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses the fan-out across SEC EDGAR, XBRL, USPTO, news, and GLEIF; mentions the USPTO PatentsView API sunset and soft-fail behavior; and notes the GDELT→GNews fallback. It also gives specific return details like the number of filings and URI format.

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

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

The description is information-dense and front-loaded with user-facing examples, but it is a single sprawling sentence with many clauses and semicolons. Despite the density, every part adds value, so it remains effective and appropriately sized 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?

With no output schema, the description does a thorough job of explaining return values: it lists CIK/company name, recent_filings (up to 5 with pipeworx URIs), fundamentals (latest 10-K fields), patents, news, and LEI. It also covers source fallbacks and input limitations, making it complete enough for an agent to invoke correctly.

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

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

The input schema already covers both parameters fully, including the enum for type and the ticker/zero-padded CIK format for value. The description mostly repeats this information with the same examples, adding no new semantic meaning beyond the schema.

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

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

The description is extremely clear: it opens with natural-language example queries and then states 'full cross-source profile of a US public company in ONE parallel call'. It also differentiates from alternative approaches by saying to prefer this over chaining single-pack SEC/XBRL/news lookups, and mentions using resolve_entity for names.

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

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

The description explicitly states when to use the tool ('when the user asks for a holistic view'), tells the agent to 'ALWAYS PREFER' it over chaining multiple lookups, and specifies that names are not supported and resolve_entity should be used first. This is strong, actionable guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it 'Returns computed result' and lists supported domains, giving useful behavioral context without contradicting 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, stating the purpose immediately, then adding a return note, examples, and usage guidance in just a few sentences. No wasted words.

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

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

Given a simple single-parameter tool with rich annotations and an output schema, the description covers purpose, usage, and examples sufficiently. It is complete for the tool's complexity.

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

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

The input schema fully documents the single 'expression' parameter with examples, and the description repeats similar examples. Since schema coverage is 100%, the description adds no additional parameter meaning beyond the schema.

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

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

The description uses a specific verb 'Evaluate' and clearly names the resource ('mathematical expressions') plus domains (arithmetic, algebra, trigonometry, statistics). This distinguishes it from sibling tools like convert_units and various research tools.

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

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

Explicitly states 'Use when you need to calculate or simplify math,' providing a clear trigger condition. It does not mention when not to use it or alternatives, but the guidance 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 declare destructiveHint=true and idempotentHint=true, so the description's 'Delete' is consistent and adds no new behavioral traits. The phrase 'clear sensitive data' offers a bit of context, but the description does not disclose what happens if the key does not exist or whether deletion is permanent. With annotations covering the safety profile, this is adequate but not rich.

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 the action, the second gives usage context, and the third places it among sibling tools. It is front-loaded with the core purpose and free of filler.

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

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

For a tool with a single parameter, clear annotations (destructive, idempotent), and no output schema, the description covers the essentials: what it does, when to use it, and how it relates to remember/recall. It does not explain error behavior, but given the low complexity and annotation coverage, it is reasonably 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?

The input schema already describes the only parameter 'key' as 'Memory key to delete,' and schema coverage is 100%. The description simply says 'by key,' adding little beyond the schema. Baseline 3 is appropriate because the schema carries the semantic weight.

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

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

The description clearly states the tool's function: 'Delete a previously stored memory by key.' It uses a specific verb ('Delete') and resource ('previously stored memory'), and explicitly differentiates from sibling tools by mentioning 'Pair with remember and recall.' This leaves no ambiguity about what the tool does.

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

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

The description provides explicit guidance on when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also acknowledges the related tools 'remember' and 'recall,' helping the agent choose between them. This goes well beyond a simple definition.

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, so the safety profile is covered. The description adds valuable context by explaining the process (fetches the page, extracts title/description/key links) and the output (single text blob in standard llms.txt markdown format), which goes beyond the annotations.

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

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

The description is concise and well-structured: three sentences front-load the main purpose, then detail the process and output, and finish with use cases. Every sentence adds value without 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?

The tool is simple, and the description covers all necessary aspects: what it does, how it works, what output to expect, and when to use it. Annotations provide safety metadata, and the schema documents parameters, so no critical information is missing.

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

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

The schema covers 100% of both parameters (url and max_links) with clear descriptions. The tool description does not add extra meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Generate a production-ready llms.txt file for any URL'. This is a specific verb+resource combination that distinguishes it from siblings like ai_visibility_check or scan_competitor_ai_presence, which focus on visibility or presence rather than file generation.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context for when to use the tool. However, it does not explicitly mention when not to use it or compare with sibling tools, so it falls short of a 5.

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

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

The annotations already establish this as a read-only, non-destructive operation. The description adds that it returns only the caller's subscriptions and specifies the exact fields returned, plus the default active-only scope. This provides meaningful behavioral context 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?

Two sentences, front-loaded with the core action, and every sentence adds value: the first states the purpose and return fields, the second gives usage guidance. 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 read-only list tool with one optional parameter, the description covers purpose, scope, return fields, and usage context. The lack of an output schema is mitigated by listing the return fields. No gaps for the tool's complexity.

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

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

The single parameter include_inactive is fully described in the schema (100% coverage), and the tool description reinforces the active/inactive distinction without adding new syntax or format details. The schema does the heavy lifting, 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 opens with 'List the caller's active subscriptions,' a specific verb+resource that clearly distinguishes from sibling subscribe/unsubscribe tools. It also enumerates the returned fields, solidifying its purpose.

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 two use cases: reviewing current monitoring before adding more and finding an ID to cancel. This contrasts with subscribe/unsubscribe, giving clear when-to-use guidance.

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

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

Annotations are neutral (readOnlyHint=false, etc.), so the description carries the behavioral burden. It discloses the claim_token mechanism for later retrieval, rate limiting ('Rate-limited to 5 per identifier per day'), and the fact that it is free and doesn't count against tool-call quota. It also explains that filing without an account returns a token, which is a non-obvious behavioral detail.

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

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

The description is longer than average but well-organized, covering purpose, usage, exclusions, token mechanics, and constraints in a logical flow. Every sentence adds relevant detail; none are redundant or fluff. It is somewhat verbose, but the density of useful guidance justifies the length.

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

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

For a simple feedback tool with no output schema, the description is remarkably complete. It covers the full lifecycle: when to file, how to file, what to include, what to avoid, what happens if no account is set (claim_token), how to check resolution, and operational constraints (rate limit, quota). The absence of an output schema is mitigated by describing the return value (claim_token and status).

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

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

The input schema covers all 4 parameters with descriptions at 100% coverage, so baseline is 3. The description adds meaning beyond the schema by explaining how the claim_token is used ('pass it back later as pipeworx_feedback({claim_token:...}) to read whether it was fixed'), clarifying what message content should be ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), and explaining type semantics indirectly. This extra context improves understanding, but since the schema already does well, the increment is modest.

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 action and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses clear verbs (tell, broken, missing, needs to exist) and unequivocally differentiates from sibling tools by scoping feedback to Pipeworx tools only, while other siblings are unrelated (e.g., 'ask_pipeworx', 'validate_claim').

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

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

The description provides explicit use cases: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives an exclusion rule: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' This clearly tells when and when not to use the tool.

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

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

The description adds valuable behavioral context beyond the annotations, including that the data is 'derived from CF analytics-engine, no PII, just (pack, tool, count)' and that results are 'Cached 5min-1h depending on window.' This informs the agent about data provenance, privacy, and freshness without contradicting the readOnlyHint or idempotentHint.

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, followed by concise use cases and technical details. Every sentence adds value without redundancy, and the structure flows logically from 'what' to 'why' to 'how.'

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

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

Given the simple one-parameter schema and lack of output schema, the description sufficiently explains what is returned (top tools, packs, call volume) and important context (no PII, caching). No additional information is needed for an agent to correctly invoke this tool.

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

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

The schema covers the 'window' parameter 100%, including its enum values and meaning ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The description mentions the window but adds little beyond the schema, so it 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 clearly states the tool's action: 'Returns the top tools, top packs, and total call volume over a recent window.' It specifies the resource (Pipeworx usage data) and the exact output, distinguishing it from sibling tools like discover_tools by focusing on what other AI agents are calling.

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

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

The 'Useful for' section provides three concrete use cases, such as discovering hot data sources and confirming canonical tool choices. However, it does not explicitly name alternatives or state when not to use the tool, so it lacks the explicit exclusions that would earn 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, openWorldHint, idempotentHint, and non-destructive. The description goes far beyond by detailing internal filters (semantic anchor Jaccard ≥0.30, placeholder partition filter), the fill_check against live CLOB depth, and the meaning of realizable_edge_pp ≤ 0. No contradictions with annotations.

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

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

The description is long but every sentence earns its place. It uses clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to organize dense information, avoiding redundancy while covering critical details.

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

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

This is a complex tool with multiple modes, filters, and a fill-check mechanism. The description fully explains the response structure (opportunities[], partition_check), edge cases (null arb signal, thin_legs), and references to related tools, making it complete given the absence of an output schema.

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

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

Although schema coverage is 100%, the description enriches both parameters with examples, accepted formats (full URLs), and the distinct semantics of `event` vs `topic`. It also explains the no-arg default, which is not evident from the schema alone.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three execution modes (trending_scan, event, topic) and differentiates from siblings like polymarket_fill_risk by noting 'For custom sizing use polymarket_fill_risk.'

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

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

The description provides explicit when-to-use guidance: 'Call with NO args for a trending_scan... pass event for... or topic for...' It recommends `event` for specific markets, gives examples, and even states when not to trade ('realizable_edge_pp ≤ 0... do not trade 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 by exposing internal algorithms (lognormal barrier, GDELT ratio, favorite-longshot bias correction), safety capping (Kelly at 0.25), caveats (24h-move warning, Fed signal unreliability), and operational details (1-hour KV cache keyed on knobs). It also explains the diagnostics structure so callers understand why segments may be empty. Nothing contradicts the readOnly/idempotent hints.

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

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

The description is long but every section is information-dense and necessary for a tool with 9 parameters and complex response semantics. It is front-loaded with the primary purpose and uses capitalization to segment sections, though the wall-of-text format could be more scannable with bullet points. Given the high complexity, the length is justified.

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

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

Since there is no output schema, the description fully compensates by specifying the response structure: by_segment with three model families, fed_candidates/fed_note, and _diagnostics including funnel counters and filter_skips. It also explains cache behavior and the meaning of each opportunity field. This gives an agent everything it needs to invoke the tool 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 description coverage is 100%, so the baseline is 3. The description adds meaningful context for the tradeable-edge knobs, especially min_partition_leg_kelly, explaining why parent-level Kelly is always 0 for partition arbs and how the per-leg Kelly works. This goes beyond the schema. However, limit and window are not elaborated further, so a 4 reflects the added value without reaching the full 5.

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 opening sentence states a specific, concrete purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly identifies the resource (Polymarket markets) and the value proposition, and the detailed segmentation into model families distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description explicitly names the intended use case ('what should I bet on today') and notes that agents can discover opportunities without paging hundreds of markets. It also gives exclusions such as Fed bets being unreliable and excluded from ranking, which is useful when-not guidance. However, it does not directly mention alternative tools or provide explicit when-to-use comparisons with its siblings, 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 readOnlyHint annotations, the description discloses substantial behavioral details: snapshots are written on cache-miss (so gaps mean no scan), history is bounded by a 60-day TTL, decay is computed from daily closes not intraday, and edge_pp_net is signed by trade direction. This is far more than annotations alone provide.

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

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

The description is long but every sentence earns its place. It is front-loaded with purpose, then clearly separates Args, RESPONSE, and LIMITS sections. The structure makes dense information easy to parse, and there is no fluff or repetition.

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

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

With no output schema, the description fully carries the burden of explaining return values. It details tracked[], expired[], and snapshot_dates[] structures, including the meaning of trend labels, decay computation, and why gaps exist. It also covers historical depth limits and data provenance, making the tool effectively self-documenting.

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

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

The input schema already describes both parameters fully, including defaults, clamps, and allowed window values. The description only repeats this information (e.g., 'default 14, max 30', 'default 1wk') without adding new meaning beyond the schema. With 100% schema coverage, 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 identifies the tool as a telemetry/analysis layer over polymarket_edges snapshots, answering a specific question ('how long has this edge existed and is it shrinking?'). It distinguishes itself from the sibling polymarket_edges tool by focusing on persistence and decay rather than live 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?

The description gives strong contextual cues for when to use this tool: to assess historical edge persistence and decay, not live snapshot values. It also includes limitations about TTL and daily-close data. However, it does not explicitly name alternatives or state 'use X instead when Y', so it stops 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 readOnlyHint annotations, the description discloses substantial behavioral details: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), identifies thin legs, and warns that partial basket fills convert an arb into an unhedged directional position. This is rich, non-obvious behavior that significantly aids the agent.

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

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

The description is dense but well-structured with uppercase mode labels and a clear 'USE THIS' callout. The content is front-loaded with the core purpose and requirements, and every sentence adds value. It is verbose for a tool description, but the complexity of dual modes justifies the length.

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

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

With no output schema, the description carries the full burden of explaining return values, and it delivers: it lists specific output fields for both single-market and basket modes, covers both parameter interpretation and risk warnings, and provides actionable usage context. This is a complete, 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?

Schema covers all parameters, but the description adds meaningful mode-specific semantics: size_usd is 'max spend on buys, target proceeds on sells' in single-market and 'settlement notional S' in basket; side defaults to 'auto from partition sum' in basket. This goes beyond the schema descriptions, though some parameters (like clamping) are left to the schema.

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

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

The description opens with a specific, non-tautological purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from siblings by naming the two modes (single-market and basket) and explicitly positioning the tool as a pre-trade risk check for polymarket_arbitrage and polymarket_edges signals.

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 instructions are provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' The description also explains when to use single-market vs basket mode and highlights the risk of partial basket fills, giving clear contextual 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 extensive behavioral context beyond the annotations: compatibility_warning conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and the caveat that real spreads are rarer than the shortcut list suggests. It also details that the response includes leg-by-leg prices and matched spread. No contradiction with readOnlyHint=true; the description consistently portrays a read-only analysis tool.

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

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

The description is longer than average but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and no redundant sentences. While it is not as terse as a one-liner, every detail serves a purpose—particularly the safety field explanations and the warning about pre-mapped vs tradeable. This earns a 4 rather than a 5 due to its length.

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

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

Given the tool's complexity (two venues, two modes, safety fields) and the absence of an output schema, the description is remarkably complete. It explains the response contents, the meaning of spread, temporal alignment, and all warning conditions. There is no critical missing behavioral information for an agent to decide when and how to invoke the tool correctly.

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

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

The schema has 100% parameter description coverage, providing baseline 3. The description adds value by explaining the topic mapping semantics, the override behavior for explicit parameters, and how the two modes interact ('Overrides the topic-mapped side'). It clarifies the meaning of each parameter beyond the schema's enum list and examples, justifying 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 opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It immediately distinguishes itself from siblings like polymarket_arbitrage by focusing on same-question cross-venue spreads and explicitly notes two modes (topic shortcuts vs explicit ticker/slug). This is a precise, unambiguous statement of what the tool does.

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

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

The description clearly explains the two usage modes and when to use each: 'TWO MODES: (1) topic — 10 pre-mapped macro shortcuts... (2) explicit kalshi_event_ticker + polymarket_event_slug for custom pairings.' It also sets expectations with 'pre-mapped ≠ tradeable' and explains when compatibility_warning fires. However, it does not explicitly name alternative sibling tools for scenarios where this tool is not appropriate, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond these: scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the dual behavior of retrieving vs listing keys. 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 two sentences, front-loaded with the primary action, and every sentence provides useful information—behavior, use case, and related tools. No filler or redundancy.

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

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

For a simple one-parameter, read-only tool with no output schema, the description covers behavior, usage, scoping, and related tools. It is fully sufficient for an agent to invoke the tool correctly.

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

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

The schema's key property description already fully explains the parameter (100% coverage). The description reinforces with examples but does not add significant new semantic meaning beyond what the schema provides, 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 action: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It explicitly distinguishes from sibling tools by naming 'remember' and 'forget', making the tool's role unmistakable.

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

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

The description provides explicit usage context: '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 pairs with 'remember' and 'forget', offering clear guidance on when to use this tool versus alternatives.

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

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

The description contradicts the readOnlyHint annotation by disclosing that mark_read:true modifies read state, which is a write operation. The annotation claims readOnlyHint=true, making the description's mention of state mutation a direct conflict.

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

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

Four sentences, each adding value: main action, return fields, filtering/read options, and alternative access. Front-loaded and free of 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?

Despite no output schema, the description describes return fields (source, citation_uri, raw payload), filtering, read-marking behavior, polling suitability, and an alternative HTTP endpoint. This is complete for a read-oriented tool.

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

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

Schema covers all parameters (100% coverage), and the description adds useful context beyond schema: examples for type ('sec_8k'), ISO timestamp format, and the effect of mark_read on subsequent calls.

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 with filtering and read-marking options. This distinguishes it from siblings like list_subscriptions and recent_changes.

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 context that polling works fine and points to an alternate HTTP endpoint for scripts/dashboards. However, it does not explicitly state when to avoid this tool or compare it to sibling tools.

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

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

Despite annotations already declaring readOnlyHint, openWorldHint, and idempotentHint, the description adds valuable behavioral context: one parallel call fanning out to multiple sources, GDELT→GNews fallback on rate limits/5xx, PatentsView soft-fail due to API sunset, and the structured return format with changes[] and citation URIs.

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 clause earns its place, front-loading user-intent triggers and then moving through mechanism, fallback behavior, and output format. Despite length, it is well-organized and contains 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?

With no output schema, the description compensates fully by specifying the return structure (changes[] grouped by source, total_changes, pipeworx:// citation URIs), covering source failure modes, and offering a clear alternative tool. The three parameters are fully documented, so no critical context is missing.

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

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

Schema coverage is 100%, establishing a baseline of 3. The description adds practical meaning beyond the schema by explaining `since` accepts ISO or relative shorthand, recommending '30d'/'1m' for monitoring, and clarifying how `value` (ticker or CIK) is used in the context of the multi-source feed.

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

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

The description clearly identifies a change feed for a company over a time window, with specific verbs and resources: SEC EDGAR filings, GDELT/GNews news, and USPTO patents. It distinguishes itself from sibling entity_profile by explicitly 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?

It provides explicit when-to-use guidance via natural-language examples, recommends typical `since` values ('30d' or '1m'), and names the alternative tool to use when static profile is needed. It also explains fallback behavior between GDELT and GNews, aiding correct tool selection.

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

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

Beyond the annotations, the description reveals that memory is 'scoped by your identifier,' that authenticated users get persistent memory, and that anonymous sessions retain memory for 24 hours. This adds meaningful behavioral context about persistence and visibility that annotations alone don't provide.

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

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

The description is five sentences but each is purposeful: it states the purpose, offers usage examples, explains scoping/persistence, and names companion tools. It is front-loaded with the core function.

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

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

For a simple two-parameter save tool, the description covers persistence behavior, TTL, scoping, and integration with recall/forget. No output schema exists, but return values are trivial for a save operation, so nothing meaningful is missing.

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

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

Schema description coverage is 100%, with both 'key' and 'value' already described in the input schema. The description only adds a high-level 'key-value pair' framing, which adds little beyond the schema.

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

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

The description uses a specific verb ('Save') and resource ('data the agent will need to reuse later'), clearly stating the tool's function. It explicitly frames persistence across conversations/sessions and distinguishes itself from sibling tools by referencing 'Pair with recall to retrieve later, forget to delete.'

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

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

The description gives explicit when-to-use guidance with concrete examples ('a resolved ticker, a target address, a user preference'). It names companion tools (recall, forget) but does not provide an explicit when-not-to-use scenario, so it falls short of the full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and no destructive hint. The description adds behavioral context: graceful degradation when GLEIF or OpenFIGI are unavailable, internal cascading lookups, and explicit labeling of unresolved identifiers. No contradiction with annotations.

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

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

The description is front-loaded with clear examples and the directive 'Use FIRST.' It is comprehensive but somewhat lengthy; however, each sentence adds unique value (degrades gracefully, internal cascade, source labeling). It could be slightly more concise by grouping the ISIN detail, but overall well-structured.

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

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

Given that schema coverage is 100% and there is no output schema, the description compensates by explaining return values (identifiers with source labels, unresolved list) and the supported types thoroughly. The tool is complex with multiple data sources, and the description covers the key behaviors (graceful degradation, internal cascade) making it sufficiently complete for an agent to use correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. However, the description adds valuable semantics: explaining that 'value' accepts ticker, CIK, ISIN, or company name for 'company' type, and brand or generic name for 'drug' type. It also clarifies that ISIN resolves to the legal entity via GLEIF mapping, which is not in the schema.

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

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

The description uses specific verbs like 'resolve' and lists concrete examples ('ticker for…', 'find the CIK for…'). It clearly identifies the tool's purpose: converting user-spoken names to canonical identifiers. It distinguishes from siblings like 'entity_profile' and 'compare_entities' by focusing on name-to-ID resolution, not further enrichment or comparison.

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

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

The description explicitly states 'Use FIRST whenever you have a name but need an ID.' This is a strong directive that prioritizes this tool over alternatives. It also implies not to use when you already have an ID, and lists supported input types (ticker, CIK, ISIN, name) so the agent knows when it applies.

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: it describes the probing mechanism (calls ai_visibility_check), the ranking logic, and the output format (ranked list with score, confidence, signal density). Annotations already declare readOnly, openWorld, idempotent, and non-destructive, which align with the description; 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?

Three focused sentences: what it does, how it works, and typical use case. Front-loaded with purpose, no filler. Every sentence contributes.

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 covers the return type and fields. It explains the process, use case, and input semantics adequately for a tool of this complexity. Sibling context and annotations further complete the picture.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not significantly enhance parameter semantics beyond what the schema already provides; it mentions entities as 'your brand + N competitors' but that is also in the schema. No added value for parameters.

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: 'Compare AI visibility across multiple entities side-by-side.' It uses a specific verb ('Compare') and resource ('AI visibility'), and distinguishes from siblings by mentioning it probes with ai_visibility_check and ranks results, which is different from single-entity check or generic compare.

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: 'Useful for competitive AI-marketing audits' and gives an example ('does Claude know about us as well as our competitors?'). It implies the tool is for multi-entity comparison, but does not explicitly contrast with alternatives like ai_visibility_check for single-entity checks.

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 behavioral traits beyond the annotations. It reveals composite fan-out behavior, partial-failure degradation, and a 5-30s latency for first-time bundlephobia measurements, plus the 'sources_failed' field. The annotations already indicate read-only and idempotent, but the description adds operational context that helps the agent set expectations and handle timeouts gracefully. 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 longer than average but well-structured and information-dense. It starts with a one-sentence purpose, then usage, output fields, ecosystem caveat, and failure behavior. Every sentence earns its place—there is no filler or repetition. It could be slightly trimmed, but the structure and front-loading make it 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?

Given the absence of an output schema, the description carries the burden of explaining the return values, which it does thoroughly: summary fields, per-advisory detail, links, and recent alternative versions. It also covers ecosystem scope and partial-failure behavior. Minor gaps include error handling for invalid package names or total source failure, but overall it is complete enough for an agent to effectively use 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?

The input schema already provides 100% coverage for both parameters: 'package' is described as an npm package name with scoped package support, and 'version' is described as optional defaulting to latest. The description adds little extra parameter-level meaning beyond the schema, though it reinforces the NPM ecosystem scope. Baseline 3 is appropriate because the schema carries the 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, action-oriented statement: "Composite 'should I add this npm package to my project' check in ONE call," clearly identifying the tool as a dependency evaluation scanner. It names the data sources (deps.dev and bundlephobia) and the specific outputs, making its unique purpose unmistakable. The description also differentiates it from broader tools by scoping it to NPM and noting that other ecosystems fall under deps.dev:version directly.

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

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

Explicit when-to-use guidance is provided: "Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'." It also clearly states when NOT to use it: "NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly," pointing to an alternative for non-NPM packages. This gives an agent clear decision criteria and a fallback path.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses concrete behavioral details: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K character cap with truncation-plus-flag, and offsets for verifying verbatim quotes. This adds substantial operational context the agent needs to use the tool correctly.

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

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

The description is efficiently front-loaded with the purpose, then gives a usage scenario, a sibling pairing, and technical parameters—all in a single dense paragraph. Every sentence adds value: no filler, no repetition of schema or annotations, and it stays easily 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?

For a tool with no output schema, the description adequately covers what the agent will receive (top-N passages, offsets, similarity scores) and important input constraints (200K truncation). It also explains the algorithmic approach and how the tool fits into a broader workflow (fetch → search within → ground), making it complete for the given complexity.

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

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

The input schema already covers all params at 100%, and the description adds meaning by explaining that 'text' is content already pulled from elsewhere (e.g., a 10-K body) and that 'query' is a natural-language request. It reinforces the limit default without needing to restate the schema, so it provides extra context rather than redundancy.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' a specific verb+resource+scope that clearly differentiates this from siblings like ask_pipeworx or ask_pipeworx_grounded. It also specifies the return format (top-N passages with offsets and similarity scores), removing any ambiguity about what the tool does.

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

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

Explicitly states when to use it ('Use when the record is too big to cram into the prompt') and names a direct alternative/companion ('Pairs with ask_pipeworx_grounded'), telling the agent to fetch with the gateway and ground over relevant passages. This gives clear decision-making context for choosing this tool over 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?

Beyond the annotations, the description reveals important behavioral details: anonymous/BYO accounts cannot persist subscriptions, phone verification is required for SMS, there is a 10/day SMS cap, and the feed is always-on with retrieval via recent_alerts or the registry endpoint. This is rich operational context with no contradiction to annotations.

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

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

The description is front-loaded with purpose and return value, and every sentence adds operational detail. It is dense but could be better organized with structured bullets for types and delivery channels; the omission of two supported types creates avoidable confusion.

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 return value, auth requirement, and most delivery channels, but omits webhook from the narrative and lists only three of five subscription types. The schema fills these gaps, but the description alone is not fully complete for a tool with this complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description largely duplicates schema examples (sec_8k, polymarket_edge, fred_series) and adds auth/return-value context, but does not meaningfully extend parameter meaning beyond the schema. It also omits two enum-supported types, though those are documented in the schema.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream' and states it returns the new subscription id, clearly distinguishing it from sibling tools like list_subscriptions and unsubscribe. The core purpose is unambiguous and action-oriented.

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 useful context such as the OAuth requirement, delivery channels, and type examples. However, it does not explicitly discuss when to use this tool versus alternatives like list_subscriptions/unsubscribe, and the 'Supported types' enumeration omits patent_grant and clinical_trial from the schema enum, which could mislead an agent about supported 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 cover safety (readOnly, idempotent, non-destructive). The description adds behavioral context beyond annotations: it explains the output consists of category-bucketed example questions with exact tool/argument shapes, and that omitting topic returns the full spread vs focusing with topic. This is useful but doesn't fully describe output size or potential latency, so a 4 is appropriate.

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 sample queries, immediately establishing purpose, then efficiently covers invocation, output, and when to use. Every sentence contributes unique value—no fluff or repetition of schema/annotations.

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

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

Given there is no output schema, the description fully covers return values (category-bucketed examples with tool/argument shapes), invocation modes, and context. It tells the agent exactly what to expect and how to choose, making it complete for a tool of this simplicity.

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 topic already described. The description adds value by giving concrete examples ('finance', 'pharma', 'betting') and clarifying the default behavior ('Omit for a cross-category spread'), which extends beyond the schema's bare enum list.

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 this is the onboarding entry point for an agent wanting to know what Pipeworx can do. It uses specific verbs like 'returns category-bucketed example questions' and distinguishes itself from siblings by positioning it as the 'FIRST' tool to use and referencing specific meta-tools to learn.

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

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

Provides clear usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools...' It also explains the optional topic parameter and when to omit it, giving explicit direction on when to use this tool vs alternatives.

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

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

Annotations already indicate non-readonly, non-destructive, and idempotent behavior. The description adds critical context that the row is deactivated rather than deleted, and that historical events remain available via recent_alerts. It also highlights ownership enforcement. This goes beyond the annotations, though it does not detail error handling or edge cases.

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

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

The description is two concise sentences. The first states the primary action, and the second explains ownership and the non-destructive side effect. No word is wasted, and the most important info is front-loaded.

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

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

For a simple one-parameter tool with no output schema, the description covers the essential behavioral aspects: operation, ownership restriction, and the deactivation (non-deletion) side effect with impact on historical data. It is sufficiently complete for an agent to understand the tool's effect.

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

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

Schema coverage is 100% and the parameter is already well-described as 'Subscription id (uuid) returned by subscribe.' The description merely repeats 'by id' without adding new semantic meaning. Thus it stays at 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 states 'Cancel a subscription by id' with a specific verb and resource. It also qualifies the action with ownership enforcement, distinguishing it from subscribe and list_subscriptions. This is clear and 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: only your own subscriptions can be canceled, and the action deactivates (not deletes) the row. It implicitly indicates when to use this tool (for canceling) but does not explicitly mention alternatives or exclusion cases. The context is sufficient without being fully explicit.

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

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

Annotations already declare readOnly/ideal conditions, and the description adds valuable context: the two routing paths, the verdict enum, that could_not_verify means the check did NOT happen and is not evidence, and that unsupported means no source exists. It also mentions verbatim evidence with pipeworx:// citations. This goes well beyond the annotations and provides essential behavioral nuance.

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

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

The description is longer than typical but every sentence serves a purpose: example queries, usage trigger, routing logic, return details, and a critical caller caveat. It is front-loaded with query examples and the core purpose, and the structure flows logically. Slightly verbose but 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?

For a tool with no output schema, the description thoroughly explains return values (verdict types, actual value, reasoning), error semantics (could_not_verify with verification_error), and the fact that it replaces 4–6 sequential calls. It covers both financial and non-financial paths, making it fully complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% for the two parameters, so the baseline is 3. The description adds extra meaning by giving real-world examples for claim and explaining how tolerance_pct overrides the implied wording tolerance, including a concrete use case for hallucination detection. This pushes it above baseline.

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

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

The description clearly states the tool verifies natural-language factual claims against authoritative sources, with explicit query examples ('Is it true that…', 'fact check'). It distinguishes itself from siblings by focusing on claim verification and even explains the two internal routing paths (SEC financial vs. grounded pipeline), making its purpose unmistakable.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a clear trigger. It also explains the behavior for different claim types and the meaning of could_not_verify vs. unsupported. However, it does not name alternative tools to use instead, so it falls short of full exclusions guidance.

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