climate

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

Annotations already, declare readOnlyHint/openWorldHint/idempotentHint, so the description adds beyond that by disclosing external network calls to LLMs, the optional BYO Anthropic key, and direct cost implications. It also explains the per-model return shape, which is not present in schema annotations. 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?

Three sentences pack the core function, default behavior, cost note, and return format with no fluff. The main purpose is front-loaded, and each sentence earns its place.

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

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

For a tool with no output schema, the description adequately explains the return structure (per-model object plus combined view) and covers all parameters implicitly through examples. Use cases are listed, and annotations fill in safety behavior. It is complete enough for an agent to invoke confidently.

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 has 100% coverage, so baseline is 3. The description adds value by clarifying the default model (Workers AI Llama-3.3-70b free) and the condition for using `_apiKey` (only when 'anthropic' is in models), which enriches the model semantics beyond 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 ('Probe') and clear resource ('one or more LLMs') plus a defined outcome ('score visibility 0-100 per model'). It distinguishes itself from siblings by focusing on AI-model knowledge visibility rather than research or entity profiles, and never resorts to vague wording.

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 three use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and provides config guidance (default free model vs. BYO Anthropic key). It does not explicitly exclude alternatives or mention when not to use this tool, which would earn a 5, but the context is clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds context by explaining the internal routing mechanism, structured answer format with pipeworx:// citation URIs, and that it works on every tier with one fast call. It does not contradict annotations and adds meaningful behavioral detail, though it doesn't mention failure modes 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 long but well-structured: it front-loads the critical 'PREFER OVER WEB SEARCH' guidance, then explains routing, gives examples, and closes with alternatives. Every sentence serves a purpose, though it could be slightly condensed without losing value.

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

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

There is no output schema, but the description explicitly states that the tool returns a structured answer with stable pipeworx:// citation URIs. It also covers usage context, tier availability, speed, and sibling trade-offs, making it complete for a tool of 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%, with 'question' and its aliases clearly described. The description provides example queries but does not add new parameter-level meaning beyond what the schema already offers. Thus, the baseline of 3 is appropriate.

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

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

The description clearly states that the tool answers factual questions by routing to one of 5,529 tools across 1,455 sources and returns structured answers with citation URIs. It uses specific verbs like 'routes', 'fills arguments', and 'returns', and explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', lists example query types ('what is', 'look up', 'find', 'get the latest', etc.), and provides clear alternatives: use ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions. This leaves no ambiguity about when 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?

Adds significant behavioral context beyond annotations: live candidate routing improvements under test, no active candidate as of 2026-07-26, current equivalence to ask_pipeworx, no fallback, and full working router status. Annotations already declare readOnly/openWorld/idempotent, and the description supplements this with dynamic experimental 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?

Four sentences, front-loaded with the core beta relationship, then current state, usage guidance, and a fallback guarantee. Every sentence carries useful information with no filler.

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

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

Given that this is a question-routing tool with no output schema, the description completely covers current operational state, experimental behavior, and equivalence to the stable router. It provides enough for an agent to select and invoke the tool correctly.

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

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

Schema description covers all six parameters (question plus five aliases), so the baseline 3 applies. The description only mentions 'same arguments' and adds no further semantic detail, but the schema already fully documents the alias relationships.

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, an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable sibling by positioning it as the experimental edge for routing improvements.

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 instructs 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router to decide what merges. It could add explicit exclusions for stable/critical use, but the context is sufficient.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses the refusal mechanism with specific refusal_reason values, the evidence verbatim quote, and the extra LLM call cost. It also explains the internal routing behavior and that the answer is extracted only from tool results. These details align with annotations and add substantial value.

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 yet every sentence serves a purpose: it opens with the core purpose, explains the mechanism, details the return format, lists refusal reasons, gives usage contexts, and notes the cost trade-off. The structure flows logically from what → how → when, and there is 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?

Given the tool's complexity and the absence of an output schema, the description compensates thoroughly by specifying the return object fields (answer, evidence, confidence, source, fetched_at, refusal_reason) and the possible refusal reasons. It also covers cost, use cases, and behavioral guarantees, making it fully self-contained for correct invocation.

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

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

The input schema has 100% coverage with six aliases for 'question', each described as a natural language query. The description does not need to add more parameter-level details because the schema already captures the semantics; 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 it is a 'Hallucination-resistant answer mode' that extracts answers only from tool results and returns evidence/refusals. It explicitly distinguishes itself from sibling ask_pipeworx by noting 'Same routing as ask_pipeworx' but adding the grounded extraction mechanism, making its purpose unambiguous.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and lists concrete high-stakes contexts (financial verdicts, legal claims, medical lookups, public statements). It also gives a clear exclusion: 'prefer ask_pipeworx for casual lookups' and mentions the cost trade-off (one extra LLM call), helping the agent decide between alternatives.

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

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

The description discloses fan-out parallelism, resolver match confidence contract, blocking statuses (low_confidence_match, market_closed_or_inactive), illiquid wide-spread flag, news fallback fields, and cancellation-rule parsing. These go well beyond the read-only/idempotent flags in annotations and describe critical safety 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 long but every section serves a purpose: classifiers, fan-out examples, response fields, resolver contract, safety behavior. It is front-loaded with the primary action and use cases, then structured with labeled sections. A bit dense, but generally each sentence earns its place.

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

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

Without an output schema, the description thoroughly documents response shapes (result.market/analysis/evidence), resolver fields, parent_event structure, news fallback flags, and status codes. It even covers edge cases like wide-spread liquidity and cancellation rules, making the tool self-contained for an agent.

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

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

The schema already documents all three parameters with descriptions (100% coverage). The description adds fan-out examples by bet category and classifier names, but it doesn't elaborate on depth/include_raw semantics beyond the schema, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource ('Research a Polymarket bet... pulling relevant Pipeworx data') and explicitly states inputs (slug/URL/question) and output (evidence packet + market-vs-model comparison). It clearly distinguishes itself from sibling tools by focusing on betting edge and market-vs-model 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?

It states concrete use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides resolution-rule warnings before sizing bets. It lacks explicit 'don't use for X' or named alternatives to other tools, so it misses the top score.

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 safety (readOnly, openWorld, idempotent), and the description adds significant behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, output format (paired data + citation URIs), and efficiency (replaces 8–15 lookups). 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?

Despite being longer than average, every sentence delivers value: query examples, explicit preference guidance, data-source details, edge-case handling, and output description. It is front-loaded with the core purpose and structured logically by entity type.

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 all essential aspects for a complex multi-type comparison tool: when to use, what data is used, how results are ordered, what the output includes, and how it compares to alternatives. No output schema exists, so the described return behavior and citation URIs fill that gap adequately.

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

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

Schema coverage is 100%, but the description adds semantic depth beyond the schema: explains what data each type pulls (10-K financials for company, adverse events/trials for drug), provides concrete examples for values (['AAPL','MSFT'], ['ozempic','mounjaro']), and clarifies the 2–5 entity scope with metrics.

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

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

Description clearly states it performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with specific verbs ('compare', 'rank') and resource scope. It distinguishes from sequential lookups and other sibling tools by focusing on entity 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?

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides concrete query patterns like 'X vs Y' and 'rank these companies'. It also differentiates when to use type='company' vs type='drug', giving clear context and an alternative strategy (avoid sequential lookups).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the tool's safety profile. The description adds that it returns side-by-side daily mean temperatures, which is useful output context, but does not disclose other behavioral traits such as data sources, model count, or error handling. This is modest extra value beyond 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 with no filler: the first states the action and scope, the second describes the output and purpose. Every word earns its place.

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

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

The description is adequate for a read-only query tool with a rich annotation set and output schema. It covers purpose and return value, and the schema handles parameter constraints, but it doesn't mention how many models are compared or any caveats, which is acceptable given the context signals.

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 all four parameters with 100% coverage, including date format and valid range. The description's reference to 'same location and date range' adds no new parameter-level detail, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Compare') and resource ('temperature projections across climate models') with scope ('same location and date range'), clearly distinguishing it from siblings like compare_entities. It also states the output (side-by-side daily mean temperatures), leaving no ambiguity.

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

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

The description gives clear context—comparing climate models for a location and date range—but does not explicitly mention when not to use it or name alternative tools. It implies a specific use case but lacks explicit exclusions or alternatives, 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?

Even with annotations declaring readOnly/openWorld/idempotent, the description adds extensive behavioral context: account requirements, depth-specific hop behavior, contradiction detection, citation resolvability, semantic excerpting, and latency expectations. This goes far beyond the annotations and helps the agent predict side effects and output characteristics.

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 each sentence adds valuable information (account, usage, internals, output, latency). It is front-loaded with the most critical operational constraint (account/sign-in) and alternatives. Minor redundancy exists in repeating 'use ask_pipeworx' twice, keeping it from a 5.

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

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

Given the tool's complexity, absence of an output schema, and the presence of rich annotations, the description covers all essential ground: prerequisites, alternatives, output structure (findings packet, gaps[], contradictions[]), limitations (breaking news gaps), and performance expectations. No critical aspect is left unexplained.

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 parameter semantics significantly. It explains depth levels ('quick=3, standard=5, thorough=8'), the hop/recovery behavior associated with each, and that 'broad/multi-part is fine' for the question parameter. This is meaningful additional guidance beyond the schema's own parameter descriptions.

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

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

The description states with a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and clearly distinguishes from siblings by noting 'this is NOT open-web search' and contrasting with ask_pipeworx. The purpose is unmistakable and unique among siblings.

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

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

Explicit when-to-use guidance is present: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. It also explains when deep_research is appropriate for broad/multi-part structured data questions.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond those: it explains the exact return shape (top-N tools with names, descriptions, full input schemas, curated examples) and notes that results are ready to call directly without a second schema lookup. 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 front-loaded with the core purpose and includes a long list of data domains. Each sentence carries information, though the domain list could be trimmed without losing the main message. Overall it's well-structured and not bloated.

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 by explaining exactly what is returned (names, descriptions, full input schemas, examples) and the direct usability of results. It gives sufficient context for when to call the tool and what to expect, making it effectively complete.

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

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

Schema description coverage is 100%, so the input schema fully documents all parameters, including aliases. The tool description reiterates that the query is a natural language description but adds no new parameter-level 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 clearly states 'Find tools by describing the data or task' with a specific verb and resource. It distinguishes itself from siblings by positioning as a meta-tool that returns the option set, and explicitly says 'Call this FIRST' when many tools are available.

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

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

The description provides explicit when-to-use guidance ('Use when you need to browse, search, look up, or discover what tools exist') and gives a strong contextual signal ('Call this FIRST'). It implies a when-not-to-use ('not just one answer') but does not name alternative tools directly.

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/idempotentHint annotations, the description discloses key behavioral traits: patents API "soft-fails until reactivated," news retrieval uses "GDELT→GNews fallback," and the requirement for ticker or zero-padded CIK. These additions provide valuable operational context.

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

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

The description is long but appropriately so for a complex multi-source tool. It is front-loaded with example queries, then systematically lists data sources and return fields. Each sentence carries useful information, though the example query list could be trimmed slightly.

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 thoroughly enumerates all return components (cik, filings with URI format, fundamentals sorted by period_end, patents, news, LEI) and input constraints. This gives an agent complete context for what to expect and how to invoke the tool.

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

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

Schema description coverage is 100%, and the schema already documents both parameters thoroughly (type enum and value with examples and the "names not supported" note). The description repeats this information without adding new meaning, so it stays at the baseline of 3.

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

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

The description opens with concrete user intents ("Tell me about X", "research Acme") and then explicitly states the tool's function: "full cross-source profile of a US public company in ONE parallel call." It clearly differentiates from sibling tools by contrasting with "chaining single-pack SEC/XBRL/news lookups" and referencing 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?

Provides explicit when-to-use guidance: "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view." It also gives a clear exclusion and alternative: "names not supported (use resolve_entity first if you only have a name)."

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 the description reinforces this by saying 'delete'. It adds context about what gets destroyed (previously stored memories) and a reason (sensitive data). No contradiction with idempotentHint=true; the description doesn't claim anything conflicting.

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

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

Three concise sentences: the first states the core action, the second gives when-to-use conditions, and the third names related tools. No redundant wording; all sentences are essential.

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 destructive tool with annotations covering safety/idempotency, the description fully covers purpose, usage, and related tools. No output schema is needed for a delete operation, and the description fits the tool's complexity.

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

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

Schema coverage is 100% and describes 'key' as 'Memory key to delete', but the description adds nuance by specifying 'previously stored memory', implying the key must reference an existing saved memory, which is meaningful beyond the schema.

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

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

The description states 'Delete a previously stored memory by key' with a specific verb (delete) and resource (memory), clearly distinguishing from siblings like remember and recall, which store and retrieve memories respectively.

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

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

Explicit usage guidance is provided: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names complementary tools: 'Pair with remember and recall,' which clarifies placement in the toolset.

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 valuable behavioral context by explaining the internal process ('Fetches the page, extracts title/description/key links') and the output format ('standard llms.txt markdown format', 'single text blob'). This goes beyond the annotations, even though it does not cover every possible edge case.

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 only three sentences, with the core action and purpose stated first. Every sentence adds value, and the 'Useful for' list is compact. No redundancy or filler content.

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

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

The tool is simple (2 params, no output schema), yet the description explains the input, process, output format, and use cases. It even mentions where to place the output ('site-root/llms.txt'). This is sufficient for an agent to invoke it confidently, though it omits potential issues like site fetch failures or rate limiting.

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 input schema already documents both parameters (url and max_links) with descriptions. The description does not add parameter-specific semantics beyond restating the output format, but the schema carries the heavy lifting, making the baseline 3 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 specific action ('Generate a production-ready llms.txt file'), the resource (any URL), and the outcome (AI crawlers can index the site). It distinguishes itself from sibling tools by focusing on generating llms.txt, which none of the siblings appear to do.

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 ('Useful for: 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'). However, it does not mention when to avoid this tool or suggest alternatives, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety. The description adds behavioral context by specifying the return format ('daily forecasts with temperature, precipitation, and weather conditions') and the time range, but does not describe data sources or potential limitations. This adds value beyond annotations without contradicting them.

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

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

The description is two sentences with no filler. The first sentence states the core purpose and scope, and the second states the return structure. Every word earns its place.

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

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

For a read-only data retrieval tool with full annotations, a 100% schema-documented parameter set, and an output schema (as indicated), the description is sufficient. It states the temporal range, the data variables (temperature, precipitation, weather conditions), and the daily granularity. No major gaps are apparent.

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

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

The input schema provides 100% coverage with descriptions for all four parameters (latitude, longitude, start_date, end_date). The description does not add additional parameter syntax or format details beyond what the schema already states, 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 uses a specific verb ('Get') and clearly identifies the resource ('historical and future temperature and precipitation projections for a location'), including the temporal range (1950–2050) and return content ('daily forecasts with temperature, precipitation, and weather conditions'). This clearly distinguishes it from 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?

The description clearly indicates when to use this tool: when needing climate projection data for a location within 1950–2050. However, it does not explicitly mention alternatives or exclusions, though no sibling tools appear to offer similar climate data functionality.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds behavioral context beyond that by specifying the scope (caller's subscriptions) and the exact return fields. No contradiction exists; the description complements the annotations.

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

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

The description is two sentences, action-first, with each clause contributing either scope, return format, or usage guidance. No filler or redundant phrasing.

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

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

For a simple list tool with one optional parameter, no output schema, and robust annotations, the description provides all necessary context: what it does, what it returns, and why to use it. The absence of non-essential details like pagination is acceptable given the tool's 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 for the sole parameter 'include_inactive' is 100% with a clear description of its behavior. The tool description adds minimal parameter-specific meaning beyond implying 'active' as default, so a baseline 3 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('the caller's active subscriptions'), clearly distinguishing this read-only tool from mutation siblings like subscribe and unsubscribe. It also enumerates the return fields, leaving no ambiguity about its function.

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

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

Explicit use context is given: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to invoke the tool, though it does not explicitly state alternatives or when not to use it.

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

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

Annotations are all false, so they convey no meaningful behavioral constraints. The description compensates richly by disclosing multiple behaviors: filing without an account returns a claim_token, passing that token back lets you read the status and resolution, the team reads digests daily, it is rate-limited to 5 per identifier per day, and it is free and doesn't count against the tool-call quota. These details add significant behavioral context that annotations do not 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 longer than typical, but every sentence carries useful information. It is front-loaded with the core purpose, then flows logically through usage conditions, excluded scenarios, content guidance, token mechanics, and operational details. While a few phrases like 'The team reads digests daily and signal directly affects roadmap' are not strictly necessary for invoking the tool, they are informative and not redundant. The structure is well-organized despite 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?

Given the tool's complexity (4 parameters, nested context object, no output schema), the description is complete. It explains how to submit feedback, what to include and exclude, how to use the claim_token for a follow-up read, and the rate-limiting behavior. Since there is no output schema, the description appropriately mentions the return of a claim_token when filing and status when checking, covering the two invocation modes adequately.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra parameter semantics by explaining the two-mode usage of claim_token: 'pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed and what changed.' It also clarifies that when passing claim_token, no other arguments should be used. This goes beyond the schema's parameter description and justifies a score above baseline.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly frames the tool as a feedback channel for bugs, feature requests, data gaps, and praise. This distinguishes it from sibling tools like ask_pipeworx and ask_pipeworx_beta, which are for queries rather than reporting issues, and it even scopes to only this connection's 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 when to use the tool: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also states when NOT to use it (for tools from other MCP servers) and directs the user to file with that server instead. The instruction to describe issues in terms of Pipeworx tools and not paste the end-user's prompt is a clear usage guideline.

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

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

Beyond the readOnly/idempotent annotations, the description adds substantial behavioral context: self-aggregating signal, derived from CF analytics-engine, no PII, cached 5min-1h depending on window, and the exact data shape (pack, tool, count). 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 front-loaded with the core purpose, followed by a well-organized bullet list of use cases, and ends with technical caveats (caching, data source, PII). Every sentence provides value and the structure makes 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?

For a simple read-only tool with one optional parameter, the description covers return format, caching behavior, privacy guarantees, and usage scenarios. Even without an output schema, the agent understands what data will come back.

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

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

The schema already provides 100% coverage of the single 'window' parameter, including enum values and their trade-offs ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The description merely restates the window options without adding new meaning, 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 a specific, distinctive statement ('What other AI agents are calling on Pipeworx right now') and clearly enumerates the outputs: top tools, top packs, and total call volume. This clearly distinguishes it from sibling tools like discover_tools and ask_pipeworx.

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' list provides three concrete scenarios (discovering hot data sources, confirming canonical tools, checking alignment with agent needs), and the window choice is explained. However, it does not explicitly name alternatives or state when NOT to use this tool, 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?

The description adds substantial behavioral context beyond the readOnlyHint annotation, including threshold-based signal triggering (>3pp deviation), placeholder filtering, skipped_low_similarity reporting, and the fill_check behavior that warns against trading when realizable edge is ≤ 0. This discloses limitations and edge cases that annotations alone do not convey, and it does not contradict the annotations.

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

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

The description is dense but well-structured: it front-loads the purpose, then logically organizes content into labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence contributes valuable operational detail without redundancy, making the length justified for a complex multi-mode 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 present, the description fully specifies the response structure (opportunities[] with fields, partition_check fields) and covers edge cases like low similarity rejections, placeholder fractions, and realizable edge conditions. This is complete enough for an agent to invoke correctly and interpret results.

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

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

Although schema coverage is 100%, the description significantly enriches both `event` and `topic` with concrete examples, mode-specific semantics, and expected output differences (e.g., partition_check in event mode). It also explains the semantic anchor and placeholder filter scenarios, going well beyond the bare schema descriptions.

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

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

The description opens with a specific verb and resource ('Find arbitrage opportunities on Polymarket') plus the method ('via monotonicity violations + partition-sum checks'), clearly distinguishing it from sibling tools like polymarket_edges and polymarket_fill_risk. It is unambiguous 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 describes three invocation modes: no args for trending scan, `event` for a specific market, and `topic` for cross-event scanning. It even recommends which mode to use for a specific market and names an alternative tool (polymarket_fill_risk) for custom sizing, providing clear when-to-use and when-not-to-use guidance.

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

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

The description adds substantial behavioral context beyond the annotations: caching behavior ('Cached 1h at the KV level'), diagnostic output (_diagnostics with funnel counters), the rationale for excluding Fed bets, the 24h-move warning ('your edge may already be in the price'), and the designed rarity of concentrated longshots. This is rich, non-redundant transparency. No contradiction with readOnlyHint or other 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 densely informational, with clear sections for response segments, knobs, and diagnostics. It uses headers and parenthetical notes to organize many details without wasted words. While it could be trimmed slightly, the complexity of the tool justifies the length and structure.

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

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

Despite lacking an output schema, the description fully explains the top-level response structure (by_segment, fed_candidates/fed_note, _diagnostics), the meaning of opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), and the filtering/funnel behavior. It is comprehensive enough for an agent to know exactly what to expect and how to interpret results.

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

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

The input schema already covers all 9 parameters with 100% description coverage, so the baseline is 3. The description goes beyond by explaining how knobs interact (e.g., min_partition_leg_kelly applies to per-leg Kelly because partition_overround parent-level kelly_fraction_half is always 0 by design) and by giving practical advice (e.g., 'Set to 5000 to drop thin-book opportunities'). This adds genuine meaning to the 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 first sentence clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' giving a specific verb and resource. It also frames the use case ('what should I bet on today') and distinguishes itself from paging hundreds of markets, making its purpose distinct even among 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?

The description provides clear context for when to use the tool: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains how to adjust tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) to filter opportunities. However, it does not explicitly mention alternatives or when not to use this tool versus siblings like polymarket_arbitrage, so it lacks explicit exclusions.

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

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

Discloses critical beyond-annotation behavior: snapshot TTL limits, cache-miss write behavior, gaps in date coverage, computation methodology (daily closes of edge_pp_net net of slippage, not intraday), and signed value semantics (negative = SELL YES). This greatly exceeds the basic readOnly/idempotent annotations and equips the agent with necessary caveats.

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

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

The description is long but well-organized with clear ARGS, RESPONSE, and LIMITS sections. It front-loads the core purpose and each section adds substantive information. Slightly verbose but every sentence earns its keep, making it structurally sound.

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 thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) and covers limitations such as history depth, TTL, and data gaps. For a complex analytical tool, this is exceptionally complete and self-sufficient.

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

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

The input schema already documents both parameters with full descriptions (days: default/clamp; window: enum values). The description merely mirrors this as 'Args' and adds no new semantic nuance beyond what the schema already provides. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description opens with a clear statement: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and differentiates itself from sibling tools like polymarket_edges by focusing on historical tracking rather than current edge computation.

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

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

Provides clear context for when to use the tool (e.g., distinguishing fresh wide edges from stale ones), but does not explicitly name alternative tools or state exclusions. The 'fresh vs 3-week-old edge' comparison implies usage, yet lacks direct guidance on when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so safety is clear. The description adds significant behavioral context beyond annotations: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), and explicitly warns about partial basket fills converting an arb into an unhedged directional position—critical risk 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 and front-loaded with the core purpose. While it is a long single paragraph, every sentence contributes necessary detail for two distinct modes, parameters, return values, and usage guidance. The structure could be improved with paragraph breaks, but no content is wasted.

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

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

With no output schema, the description fully compensates by enumerating all return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, max_clean_notional_usd, forced_directional_risk). It also explains the underlying risk rationale, making it complete for a complex trading 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?

Although the schema already describes all four parameters, the description adds key semantics: it states the mutual exclusivity of market vs. event, clarifies how size_usd is interpreted differently (max spend on buys, target proceeds on sells, settlement notional in basket mode), and explains the side options for each mode. These insights go beyond the schema descriptions.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from sibling tools by explicitly stating 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' positioning it as a pre-trade risk check.

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

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

Provides explicit when-to-use instructions with direct reference to sibling tools and a dollar threshold. It also explains the two modes (single-market vs. basket) and when each is appropriate, including defaults for side and size_usd, giving the agent clear decision criteria.

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

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

The description goes far beyond the annotations by explaining the response structure (leg-by-leg prices, spread, compatibility_warning conditions), temporal_alignment semantics, and skipped_cross_type/subtype counters. It discloses edge cases such as matched_pairs:0 with non-equivalent bet shapes and how to interpret them. No contradiction with the readOnly/openWorld/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 lengthy but well-structured with sections (modes, response, safety fields). Every sentence contributes unique information about behavior or edge cases. It could be trimmed, but the density and organization justify the length for a complex tool.

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

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

Given the tool's complexity and lack of output schema, the description is remarkably complete. It covers all parameter behaviors, response format, compatibility warnings, temporal alignment, and practical caveats. An agent would have sufficient understanding to select and invoke this tool correctly.

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

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

Schema coverage is 100% with parameter descriptions, so the baseline is 3. The description adds meaningful interaction semantics: topic is auto-mapped, explicit tickers override the mapped side, and the relationship between parameters is clarified. This elevates it slightly above baseline.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this from sibling tools like polymarket_arbitrage or polymarket_edges by focusing on cross-venue comparison and compatibility warnings. The two modes (topic shortcuts vs explicit tickers) are explicitly stated.

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 strong usage context: when to use each mode ('topic' vs explicit tickers), and when the tool is reliable vs not ('when the bet shapes are equivalent... when they aren't the tool says so'). It also warns that pre-mapped topics often return compatibility_warning and are not necessarily tradeable. However, it does not explicitly name alternative tools for comparison, 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, destructiveHint=false. The description adds meaningful behavioral context: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and the dual-mode behavior (retrieve vs list all keys). 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?

Three sentences, front-loaded with the primary function, and every sentence earns its place — no redundancy or filler.

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

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

For a tool with one optional parameter, no output schema, and strong annotations, the description fully covers purpose, usage context, scope, and pairing with siblings. It is complete.

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

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

Schema coverage is 100% for the 'key' parameter, so baseline is 3. The description adds practical examples of key contents (target ticker, address, research notes) and reiterates the omit-to-list-all behavior, enriching semantics slightly beyond the schema.

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

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

The description opens with a specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes from sibling tools (remember/forget) by naming them and describing the read-only retrieval action.

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

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

Explicitly states when to use: 'Use to look up context the agent stored earlier' and names the paired operations: 'Pair with remember to save, forget to delete.' This provides clear context and alternatives.

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

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

Annotations declare readOnlyHint=true, but the description explicitly describes mark_read:true as flagging events read, which mutates state. This directly contradicts the read-only hint, lowering the score to 1.

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

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

Two dense sentences with no filler; every clause adds functional information (return fields, filtering, mark_read, polling, alternative endpoint).

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?

Description covers return value structure (source, citation_uri, raw payload), filtering, read-flag side effect, polling suitability, and HTTP mirror, making it self-sufficient without an output schema.

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

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

Schema already covers all 5 parameters, but the description adds behavioral nuance for mark_read (only newer events on next call) and clarifies type/since usage, exceeding schema info.

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 'Pull fired events from your subscription feed' and further clarifies it returns recent alerts with payload details, distinguishing it from subscription management tools like subscribe/unsubscribe.

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 advises polling works fine and directs scripts/dashboards to an HTTP endpoint, providing clear context for interactive use vs automation. However, it doesn't explicitly name alternative MCP tools, so it's not a perfect 5.

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

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

The description goes well beyond annotations by disclosing the parallel fan-out to SEC EDGAR, GDELT, GNews, and USPTO, including fallback triggers (rate limits/5xx) and soft-fail conditions (PatentsView API sunset). It also specifies the exact return structure (changes[] grouped by source, total_changes, 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 sentence delivers value: examples, core function, source details, fallback logic, parameter formats, output summary, and an explicit alternative. It is front-loaded with user-intent examples and avoids redundancy with the schema.

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

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

Given the tool's complexity (multi-source, fallbacks, time-window semantics), the description covers all critical operational aspects: data sources, fallback behavior, input formats, output structure, and a clear pointer to an alternative tool. No output schema exists, so the description rightly explains return values (changes[], total_changes, 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?

Schema coverage is 100%, and the description adds extra guidance for the `since` parameter (e.g., 'Use "30d" or "1m" for typical monitoring') and clarifies supported relative formats. It does not add much for `type` and `value`, but the schema already provides adequate descriptions.

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

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

The description clearly identifies the tool as a change feed for a company over a recent window, with explicit query examples like "What's new with X". It distinguishes itself from the sibling entity_profile by contrasting window-based changes vs static profile.

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

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

Provides explicit when-to-use context via query patterns, and explicitly names the alternative: 'Use entity_profile instead when you want the static profile'. Also explains the data source fallback behavior (GDELT→GNews) as a usage consideration.

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 (idempotent, non-destructive), the description adds key behavioral details: storage is a key-value pair scoped by agent identifier, persistence is permanent for authenticated users, and anonymous sessions keep memory for 24 hours. This is valuable operational context not present in the schema or 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?

Four sentences pack in function, examples, storage model, and companion tools without fluff. Slightly longer than necessary, but every clause contributes to agent understanding.

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 write tool with full schema coverage and no output schema, the description is complete. It explains the storage mechanism, persistence rules, and how the tool relates to recall and forget, leaving little ambiguity.

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

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

Input schema already describes both key and value with 100% coverage. The description adds illustrative examples but no new semantics beyond what the schema conveys, so the baseline of 3 applies as the schema does the heavy lifting.

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

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

Description uses a specific verb 'Save' and clarifies exactly what is stored and why — data needed for reuse across the conversation or sessions. It provides concrete examples and implicitly distinguishes itself from siblings recall and forget, which retrieve and delete respectively.

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?

Description explicitly states when to use it ('Use when you discover something worth carrying forward...') and gives realistic examples such as resolved tickers and user preferences. It also points to companion tools (recall for retrieval, forget for deletion), which helps the agent choose correctly among 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?

Beyond the annotations (read-only, idempotent), the description adds valuable behavioral details: unresolved identifiers are explicitly listed rather than omitted, LEI/FIGI enrichment degrades gracefully when sources are unavailable, each identifier is source-labeled, and the tool cascades through multiple endpoints. No contradiction with annotations.

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

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

The description is long but front-loaded with examples and a clear statement of purpose. Each sentence serves a purpose: examples, supported types, fallback behavior, and efficiency. It is structured with clear section labels (SUPPORTED TYPES) and reads naturally. Slightly verbose but not padded.

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 details the return behavior for both entity types, including source identifiers (CIK, LEI, FIGI, RxCUI), failure handling ('unresolved' field), graceful degradation, and the internal cascading lookups. It covers all important aspects an agent needs to understand the tool's outcomes and limitations.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema: it clarifies what each 'type' resolves to (e.g., company returns CIK+ticker+LEI+FIGI, drug returns RxCUI+ingredient+brand), provides real-world input examples, and explains accepted input formats (ticker, CIK, name; brand or generic). This enhances parameter understanding.

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 ('resolve') and resource ('entity name to canonical/official identifiers') and provides numerous concrete examples ('ticker for…', 'CIK for…', 'LEI for…'). It clearly distinguishes itself from siblings by focusing exclusively on name-to-ID resolution, not profiles or comparisons.

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

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

It gives an explicit when-to-use directive: 'Use FIRST whenever you have a name but need an ID.' It also elaborates on the two supported types and the inputs each accepts. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint: false), the description discloses that the tool probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It also specifies the return structure (ranked list with score, confidence, signal density). This adds meaningful behavioral context about the tool's internal multi-probe aggregation behavior and output 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 concise and well-structured. It opens with the core function, then explains the mechanism, offers a practical use case, and states the return format. Every sentence earns its place with no redundancy or filler.

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

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

Given the tool's moderate complexity (multi-probe comparison), the description is complete. It explains the process, the use case, and—since there is no output schema—explicitly lists the return fields (score, confidence, signal density). The annotations and schema cover the remaining safety and parameter details, making the description sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant parameter-level detail beyond the schema; it references entities and competitors in prose but the schema already fully documents each parameter including the 'first entry as subject' semantics. No additional parameter meaning is provided.

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: comparing AI visibility across multiple entities side-by-side. It uses a specific verb ('Compare') and resource ('AI visibility across multiple entities'). It also distinguishes itself from likely siblings like ai_visibility_check (single entity) and compare_models (comparing models) by emphasizing multi-entity comparison for competitive audits.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and gives an example question. It implies when to use it (when comparing multiple entities) but does not explicitly mention alternatives or when not to use it. The context is clear and actionable, though it lacks exclusions or direct contrasts with 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?

Beyond annotations (readOnlyHint, idempotentHint), the description discloses important behavioral traits: it's a composite call that fans out to multiple sources, handles partial failures gracefully, notes that bundlephobia's first measurement can take 5-30s, and includes a sources_failed field. This adds significant context not available from 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 yet comprehensive, front-loaded with a clear summary, then usage, return value details, limitations, and failure behavior. Every sentence adds value, and the structure is logical with 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?

With no output schema, the description fully explains the return structure: summary block fields, per-advisory detail, links, and alternative versions. It also covers edge cases (partial failures, latency) and provides ecosystem limitations. The description is complete for a complex composite 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 clear descriptions for both parameters with 100% coverage. The description doesn't add further parameter-level meaning beyond what the schema states, but it does contextualize the package name and version in the overall purpose. Baseline of 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose as a composite 'should I add this npm package to my project' check that fans out across deps.dev and bundlephobia. It specifies the exact resources (npm package) and the scope (license, advisories, bundle size, etc.), distinguishing it from any sibling tool.

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

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

Explicit usage guidance is given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also provides a clear exclusion for non-NPM ecosystems, directing users to use deps.dev:version directly for PyPI/Maven/Cargo/Go.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds rich behavioral context beyond that: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K character cap with truncation and flagging, and return details (offsets, similarity scores). 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?

Although lengthy, every sentence contributes value: the core function, use case, return format, pairing guidance, and technical limits. It is front-loaded with the main purpose and avoids fluff, earning 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?

For a tool with no output schema, the description adequately covers input constraints, algorithm, truncation behavior, and return format (character offsets and similarity scores). It also provides integration context with ask_pipeworx_grounded, making it highly complete for its 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 baseline is 3. The description adds some context for the query parameter with examples (e.g., 'supply-chain risk') and clarifies the text is 'already pulled,' but it largely echoes the schema. It doesn't provide significant new semantic meaning beyond the schema definitions.

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

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

The description uses a specific verb phrase 'Semantic search INSIDE a fetched record' and clearly identifies the resource (the text parameter). It differentiates from siblings by explicitly pairing with ask_pipeworx_grounded and noting the use case of reducing context load.

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 guidance: 'Use when the record is too big to cram into the prompt' and explains how it pairs with ask_pipeworx_grounded. This distinguishes when to use search_within versus alternatives, satisfying the when-to-use requirement.

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

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

The description discloses important behavioral traits beyond annotations, including authentication requirements, phone verification, SMS caps, and the always-on feed behavior. It also clarifies that the tool is a write operation (consistent with readOnlyHint=false) and adds constraints like the 10/day cap, which annotations do not cover.

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, starting with the core purpose and then detailing types and delivery. Every sentence provides necessary information, though it is a single paragraph that could benefit from bullet points for readability. It is not overly verbose given the tool's complexity.

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

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

The description covers the return value, authentication prerequisites, all supported subscription types with examples, and delivery channel specifics (feed, email, SMS). However, it omits the webhook delivery channel entirely, which is present in the schema; this oversight is minor because the schema provides that detail, but the description would be more complete if it mentioned all available delivery options.

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?

Even though the schema has 100% parameter description coverage, the tool description adds significant meaning by providing concrete examples for each subscription type (e.g., sec_8k with items:["5.02"]) and clarifying delivery parameter formats. This goes well beyond the schema's generic property descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream, which is a specific verb+resource. It also distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on the creation act and noting it returns a new subscription id.

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

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

The description provides clear context for when to use the tool by listing required authentication (Pipeworx OAuth account), supported types, and delivery options. It also gives implicit alternatives by referencing recent_alerts and the registry URL for pulling feed data, but does not explicitly state when not to use this tool compared to other subscription-related tools.

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

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

Annotations already provide the safety profile (readOnly, idempotent, non-destructive). The description adds valuable context about the live catalog source, category-bucketed output, and the ability to call with no arguments or a topic focus. 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-loaded with common user phrasings and well-organized into purpose, output details, and usage. Every clause adds useful context; the only minor issue is a slightly dense list of categories and meta-tools that could be trimmed.

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

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

Even without an output schema, the description explains what is returned (category-bucketed example questions with exact tool + argument shape), how to invoke it, and when to use it. This is complete for an onboarding/discovery tool.

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

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

The single optional `topic` parameter is fully described in the schema with an enum-like list and the default 'omit for cross-category spread'. The description adds examples and clarifies the focus behavior, but largely mirrors the schema, so it does not significantly exceed 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 identifies this as the onboarding entry point for discovering what to ask Pipeworx, and explicitly states it returns category-bucketed example questions with the exact tool and argument shape. It distinguishes itself from sibling research/execution tools by focusing on 'what can I ask' rather than performing a task.

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

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

It gives explicit usage direction: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to use it for learning meta-tools. It also mentions alternatives by name (ask_pipeworx, entity_profile, compare_entities) and provides a clear fallback scenario.

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 indicate idempotency and non-destructiveness, but the description adds valuable behavioral detail: ownership enforcement, deactivation rather than deletion, and the side effect on recent_alerts. This goes beyond what annotations provide and gives the agent important operational context. No contradiction with annotations.

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

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

Two sentences, front-loaded with the core action, followed by essential constraints and side effects. Every sentence earns its place with no redundant or filler content.

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

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

For a single-parameter tool with good annotations and no output schema, the description covers the purpose, usage constraints, and behavioral outcomes completely. It leaves no critical questions about when or how to invoke the tool.

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

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

Schema description coverage is 100%, with the parameter 'id' already described as 'Subscription id (uuid) returned by subscribe.' The description only adds 'by id' and an ownership constraint, which does not substantially augment the schema. The baseline of 3 is appropriate when the schema carries the parameter documentation.

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

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

The description uses a specific verb 'Cancel' with a clear resource 'subscription' and method 'by id'. It clearly distinguishes from sibling tools like subscribe (creation) and list_subscriptions (viewing), making the tool's purpose unambiguous.

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

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

The description provides clear context for use: ownership is enforced, so only your own subscriptions can be canceled, and the row is deactivated to preserve history via recent_alerts. It implies when to use (stop future alerts but keep historical events) but does not explicitly mention alternative tools or exclusions, 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 readOnly/idempotent/openWorld annotations, the description discloses critical behavioral nuances: the distinction between 'unsupported' (no source found) and 'could_not_verify' (verification failed due to LLM/source error), the presence of verification_error details, and an explicit warning that could_not_verify must not be treated as evidence. It also explains the routing logic between financial and non-financial claims and mentions verbatim evidence and pipeworx:// citations.

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: trigger phrases, primary use, routing details, verdict types, error semantics, and efficiency note are all packed without redundancy. The front-loading of natural-language triggers makes the purpose immediately recognizable, and the 'IMPORTANT for callers' section highlights the most critical behavioral trap.

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 no output schema, the description fully covers return values (verdict list), evidence format (grounded/structured value with citation), error handling (could_not_verify with verification_error), and the distinction between unsupported and could_not_verify. It also explains the internal routing to authoritative sources, making the tool's behavior predictable for an agent. The openness annotations (openWorldHint) align with the fallback behavior.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a little context about '"exact percent-delta math"' for financial claims and the tolerance cap, but most parameter meaning (claim examples, tolerance_pct override and default) is already fully captured in the input schema. No significant additional semantics are needed beyond what structured fields provide.

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

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

The description starts with explicit trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…') and states the tool verifies natural-language claims against authoritative sources. It clearly distinguishes itself from siblings like deep_research or ask_pipeworx by focusing on fact-checking with verdicts, and mentions a unique two-path routing (SEC EDGAR for financial claims, grounded pipeline otherwise).

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 direct when-to-use guidance. It also contrasts with a 4–6 sequential-call alternative, suggesting it is a one-call replacement. However, it does not name specific sibling tools or state when not to use this tool in favor of another, so it falls just 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.