Gets Nz

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is clear. The description adds behavioral detail: it calls external LLMs, requires a BYO key for Anthropic (with cost implication), and returns per-model scores. It does not disclose potential rate limits or caching, but overall adds sufficient context 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?

The description is four sentences long with no redundant information. The first sentence front-loads the core action and output, followed by model details, return format, and use cases. Every sentence adds value, making it efficient for an AI agent to parse.

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 details the return structure (per-model object with score, confidence, signals, raw_response, plus combined view). Use cases are provided. Missing elements like error handling or pagination are acceptable given the tool's simplicity and the presence of comprehensive annotations.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches parameter semantics by explaining the default model behavior, the conditional use of _apiKey, and the disambiguation role of context. This goes beyond the schema's descriptions, adding practical guidance for parameter values.

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 the verb 'probe' and specifies the resource (LLMs) and the output (visibility score 0-100 per model). It clearly distinguishes the tool's purpose from siblings like ask_pipeworx by focusing on multi-model visibility scoring rather than single entity Q&A. The mention of specific use cases (AI-marketing audits, pre-launch brand checks) further clarifies its niche.

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

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

The description states when to use the tool (for AI-marketing audits, pre-launch brand checks, competitive monitoring) and gives model selection guidance (default workers-ai, optional Anthropic with BYO key). However, it does not explicitly list when not to use it or suggest alternative tools for narrower questions, leaving some ambiguity for an AI agent.

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

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

Annotations already signal read-only, idempotent, open-world, non-destructive behavior. The description adds real behavioral context by explaining the routing mechanism, argument-filling, structured output, and stable citation IRIs, and notes that breaking-news queries route to live news feeds. It could go further by noting limitations or answer-confidence tradeoffs, but the annotations cover the core safety profile.

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

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

The description is front-loaded with the most important instruction ('REFER OVER WEB SEARCH') and then moves through scope, behavior, triggers, examples, and alternatives. It is somewhat long and has minor redundancy ('even if web search could also answer it' echoes the opening line, and 'START HERE' repeats the preference), but each section 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 single-string-parameter tool with no output schema, the description is quite complete: it names input patterns, output form (structured answer with citation IRIs), source categories, and sibling routing. It doesn't explicitly state when not to use it for non-factual/non-research queries, but the factual framing makes that boundary reasonably clear.

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 value by giving concrete example questions ('current US unemployment rate', 'Apple's latest 10-K', 'active clinical trials for GLP-1') and by specifying the acceptable input domain as natural-language factual queries, which goes beyond the schema's generic 'Your question or request in natural language'.

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 what the tool does: it routes factual questions to the appropriate one of 5,767 tools across 1,506 verified sources, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It also differentiates itself from web search and sibling tools such as 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?

It explicitly says 'PREFER OVER WEB SEARCH' for a wide range of factual queries and lists trigger phrases like 'what is', 'look up', 'find', and 'get the latest'. It also gives clear when-not-to-use guidance: ask_pipeworx_grounded for narrow ground-truth claims needing verbatim evidence, and deep_research for broad multi-part 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds meaningful context beyond annotations: it is a full working router, not a fallback; candidate improvements are enabled live; none is currently active; results are compared against the stable router for merge decisions. It also clarifies that behavior may differ between beta and stable versions when candidates are active, but currently matches exactly.

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

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

The description is appropriately sized for a beta variant and front-loads the key fact that it's a beta version. It explains identity, current state, usage, and the comparison workflow in a compact paragraph. Slightly dense with details like the retirement date and tool count, but those are specific and relevant.

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 router tool with a fully documented schema and rich annotations, the description covers identity, current parity with the stable version, fallback behavior, and how to use it. No output schema exists, but since the response shape is stated as identical to ask_pipeworx, an agent has all necessary context to invoke it correctly.

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

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

Schema coverage is 100%, and the schema already describes 'question' and all aliases. The description adds little beyond saying 'same arguments' as ask_pipeworx and that the router accepts a natural-language question/request. Since the schema fully documents the single meaningful parameter, the baseline of 3 applies; the description doesn't need to add much.

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

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

The description is specific: it identifies this tool as the beta/experimental edge of ask_pipeworx, explicitly stating it is the same universal router with the same tools, arguments, and response shape. It distinguishes it from the stable ask_pipeworx sibling by its purpose of testing candidate routing improvements, and even names the current state (no active candidate, identical to 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 description states when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also contrasts with ask_pipeworx as the stable router and explains that results are compared to decide what merges. This gives explicit when-to-use and an implicit alternative (ask_pipeworx for stable routing).

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

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

Beyond the annotations (readOnlyHint=true, idempotentHint=true, openWorldHint=true), the description richly discloses behavior: routing across 5,767 tools and 1506 sources, extraction limited strictly to tool-result content, exact success payload with verbatim evidence, and an enumerated refusal_reason set covering failure modes like not_in_source, no_tool_match, tool_error, data_truncated, and llm_error. The refusal behavior in particular is valuable context annotations could never convey.

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

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

Every sentence earns its place: mode identity, routing mechanism, extraction constraint, success shape, refusal shape, usage domains, and cost tradeoff. The refusal_reason enum is the only borderline-verbose element, but it directly helps an agent handle failure gracefully. Information is front-loaded with the differentiator first.

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

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

With no output schema present, the description fully compensates by specifying both the success and refusal return structures, including the verbatim evidence field and refusal reason taxonomy. Combined with annotations covering safety/idempotence and a 100%-covered input schema, nothing an agent needs to invoke this tool correctly or interpret its result is missing.

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

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

Schema description coverage is 100% — the schema already documents 'question' as natural language with five aliases. The description adds contextual meaning (the question is routed to fill sub-tool arguments), but does not introduce parameter-level syntax or format details, so the baseline 3 for high schema coverage 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 states a specific verb+resource mode ('Hallucination-resistant answer mode for high-stakes reads') and immediately differentiates from the sibling ask_pipeworx by explaining the same routing followed by source-grounded extraction. A second sentence lays out the exact success and refusal return shapes, so an agent knows precisely what this tool is and is not.

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

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

Explicit when-to-use guidance is given: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete domains (financial verdicts, legal claims, medical lookups, public statements). It also names the alternative (ask_pipeworx) and the condition for preferring it ('casual lookups') based on the one-extra-LLM-call cost tradeoff. Nothing is left to inference.

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 reveals extensive behavioral details beyond the annotations: resolution matching confidence, parent event extraction, news fallback mechanisms, safety short-circuits for low-confidence or closed markets, tradeability warnings, and cancellation rule parsing. All disclosures are consistent with the readOnlyHint and idempotentHint 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 information-dense and uses section-like markers (RESOLVER CONTRACT, PARENT_EVENT, etc.) which help structure. However, it is quite lengthy and may overwhelm an agent with details; some sentences are very specific and could be considered verbose. It earns its place but could be more concise.

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 no output schema, the description provides detailed coverage of return shapes (result.market, result.analysis, result.evidence), edge cases (low confidence, closed markets, wide spreads), and cancellation rules. It is thorough and leaves few gaps for the agent to infer.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that the 'market' parameter accepts slug, URL, or question text, and provides context for 'depth' (quick vs thorough) and 'include_raw' (summary vs full payload). This goes beyond the schema descriptions.

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

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

The description clearly states that the tool researches a Polymarket bet, resolves the market, classifies it, fans out to data sources, and returns an evidence packet with comparison. It provides specific use cases ('should I bet on X') which distinguishes it from sibling tools like polymarket_edges or valid_claim.

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

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

The description explicitly states when to use the tool (e.g., 'should I bet on X', 'is there edge in Z') and provides examples of fan-out. However, it does not explicitly mention alternatives among siblings or when not to use it, leaving some guidance implicit.

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

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

Beyond annotations (readOnlyHint, openWorldHint, etc.), the description adds critical behavioral details: data sources (SEC, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URI returns. 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 thorough but slightly lengthy; however, it is well-structured with example queries first, then behavior details. Every sentence adds value, but could be tightened 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?

Given no output schema, the description explains output (paired data + citation URIs). It covers both entity types, constraints (2-5 items), and key behaviors, leaving no major gaps for an agent to invoke correctly.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning by explaining type enum values ('company' or 'drug') and values as tickers/CIKs or drug names, with examples and max constraint, enhancing the schema's basic description.

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

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

The description uses specific verb 'compare' and resource 'entities', provides multiple query examples ('X vs Y', 'which is bigger'), and explicitly distinguishes from siblings by stating 'ALWAYS PREFER over sequential single-pack lookups'.

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

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

The description clearly advises using this tool over sequential lookups and specifies it replaces 8-15 calls. However, it lacks explicit when-not-to-use scenarios, such as when more granular data is needed beyond the listed metrics.

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

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

Annotations already cover readOnly/openWorld/idempotent, and the description adds substantial context on top: auth prerequisites (free GitHub sign-in, thorough requires a paid plan), latency expectations (15-60s, thorough up to ~90s), the return packet structure (verbatim evidence + confidence + source + fetched_at + citation), the 'never invented' gap[] guarantee, and the fetchability guarantee for citation URIs. No contradiction with annotations — the read-only, idempotent research behavior is consistent with the described design.

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

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

The description is long, but the tool is genuinely complex (3 depth modes, auth tiers, citation semantics, gap recovery) and every sentence carries distinct information — auth gate first, then alternative routing, then capability, then return format, then timing. It is front-loaded with the most decision-critical facts. It loses a point for being a single dense run-on paragraph with heavy parentheticals, which taxes an agent's parsing.

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

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

With no output schema, the description carries the full burden of explaining return values — and it does: findings packet fields, gaps[], contradictions[], hop field, citation_uri behavior, and semantic excerpting. Also covered are auth prerequisites, failure mode when the topic isn't in the catalog, latency, and alternative tools. For a tool of this complexity with zero output schema, nothing an agent needs to call it correctly or interpret its results is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it ties depth modes to their behavioral consequences (which modes return contradictions[], hop behavior, timing, paid requirement for thorough) and clarifies the question parameter's intent ('Broad/multi-part is fine — decomposition is the point'). This goes beyond restating 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?

States a specific verb+resource — 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources' — and sharply distinguishes itself from open-web search ('this is NOT open-web search'). It also names what it is not relative to siblings by steering single lookups to ask_pipeworx. The purpose is unmistakable even before reading the schema.

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

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

Gives explicit when-to-use ('Best for broad/multi-part questions over structured data') with concrete examples, and three explicit when-not-to-use routes: not signed in → ask_pipeworx; single lookup → ask_pipeworx; breaking/colloquial news → ask_pipeworx. The alternative-selection logic is fully spelled out, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds that it returns top-N relevant tools with schemas and examples, and that results are ready to call directly. This adds value without contradicting annotations.

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

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

The description is somewhat lengthy with repetitive points about schemas and examples. While front-loaded with purpose, it could be more concise without losing meaning.

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 meta-purpose and rich schema, the description sufficiently explains functionality, return value, and usage context. It covers what an agent needs to use it effectively.

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

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

Schema covers all 6 parameters with descriptions. The description adds context by explaining what the query should contain via examples and mentions aliases, enhancing usability beyond the schema.

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

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

The description clearly states the tool finds tools by describing data or task, distinguishes itself from sibling tools by being a meta-tool for discovery, and lists specific domains.

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 when to use: when browsing, searching, or discovering tools, and even advises to call it FIRST. It lacks explicit scenarios to not use it, but the guidance is strong.

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

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

Goes well beyond the readOnly/idempotent annotations by detailing fan-out sources, `sources_used`/`sources_failed` semantics, the patents soft-fail, expected-empty FDA product sections, and private-company resolved:false behavior. These are exactly the behavioral quirks an agent needs to interpret results correctly.

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

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

Front-loaded with purpose and usage examples, and every sentence carries substantive information. The large return-section list is packed into one dense paragraph; bullets would improve scannability, but nothing is redundant for the tool's complexity.

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

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

With no output schema, the description enumerates every return section, source coverage, failure semantics, and input resolution behavior. An agent can invoke this tool and interpret its response without 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?

Schema description coverage is 100%, so the parameters are already fully documented. The description adds useful examples and reiterates interchangeability, but most of the added context concerns output behavior rather than new parameter 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?

States exactly what the tool does — returns a full multi-source profile of a US public company in one call — and supports it with concrete user phrasings. It explicitly distinguishes itself from chaining single-pack SEC/XBRL/news lookups, so an agent can route holistic inquiries here confidently.

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

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

The description gives an explicit ALWAYS PREFER directive for holistic-company-view requests over chain-of-single-topic lookups, and explains the three accepted input forms plus the private-company edge case. This is actionable routing guidance, not just a vague capability statement.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds functional context about deletion and use cases but does not disclose additional behavioral nuances beyond the annotations (e.g., behavior on missing key, permanence of deletion). With annotations covering the core safety profile, the description adds moderate 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 extremely concise (two sentences) with no redundant or filler content. The first sentence states the core action, the second gives usage context and sibling references. Every sentence earns its place.

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

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

For a simple tool with one required parameter, clear annotations, and a single action, the description is largely complete. It covers purpose, usage guidance, and relation to siblings. Minor omission: no mention of error handling or idempotency behavior, but overall adequate for the tool's complexity.

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

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

Schema coverage is 100%, so the schema already documents the 'key' parameter and its description. The tool description does not add any additional meaning or usage details for the parameter beyond 'Memory key to delete'. Baseline 3 is appropriate.

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

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

The description clearly states the action 'Delete a previously stored memory by key'. It specifies the resource (memory) and operation (delete/forget). It distinguishes from sibling tools like remember and recall by explicitly naming them and positioning forget as the deletion counterpart.

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 context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with remember and recall, clarifying when this tool is appropriate vs alternatives.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: fetches the page, extracts title/description/key links, and emits standard markdown. No contradictions, and the description enriches 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?

The description is a single paragraph, front-loaded with the core purpose in the first sentence, and every sentence adds value with no redundancy. It efficiently covers purpose, process, use cases, and output format.

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 has 2 parameters, no output schema, and rich annotations, the description explains the output format ('single text blob'), the process (fetches, extracts), and use cases, leaving no obvious gaps for an agent to select or 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 coverage is 100% with clear descriptions for both parameters. The description mentions fetching and extracting, which implies the url parameter's purpose, and 'maximum number of link entries' hints at max_links. However, it adds minimal new semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb (generate), resource (llms.txt), and scope (for AI crawlers). It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on generating the standard file format rather than scanning.

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

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

Explicitly lists three use cases: getting a client's site indexed, drafting for own project, auditing competitor. Provides clear context for when to use, though does not explicitly mention when not to use or alternative tools.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by specifying the returned fields and the optional 'include_inactive' parameter's effect. It does not contradict annotations.

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

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

The description is two sentences long with no redundant words. The first sentence lists purpose and outputs, the second provides usage guidance. Every sentence serves a purpose.

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

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

Given the simplicity of the tool (no output schema, one optional parameter), the description is largely complete. It states the scope ('caller's active'), lists return fields, and provides usage advice. It could mention lack of pagination but is 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 schema covers the single parameter completely (100% coverage). The description does not add additional meaning to the parameter beyond its schema definition, but it implies the parameter's effect through context. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, specifying the verb 'list' and the resource 'subscriptions'. It also enumerates the return fields, making the purpose explicit. This distinguishes it from sibling tools like 'subscribe' and '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?

The description advises to use the tool 'to review what you're monitoring before adding more or to find an id to cancel'. This provides clear usage context but does not explicitly mention when not to use it or contrast with other tools like 'subscribe'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's behavioral disclosure is less critical. However, the description adds useful context by listing the specific fields returned, such as tender name, dates, and URL, which aids agent understanding.

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

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

The description is a single, well-structured sentence that front-loads the purpose, then provides the ID source and example, and lists returned fields. Every part adds value without redundancy.

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

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

For a simple tool with one parameter and no output schema, the description is fairly complete. It details the returned data extensively. Lacking explicit error handling or validation messages is acceptable given the simplicity and rich annotations.

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

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

The input schema has 100% coverage, but the description adds meaning by explaining that the ID is numeric and comes from sibling tools, providing an example (32705858). This clarifies the parameter's origin and format beyond the schema's brief description.

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

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

The description uses a specific verb ('Fetch') and identifies the resource ('full detail for a single New Zealand government tender from GETS'), with a unique identifier (RFx ID). It implicitly distinguishes from siblings like nz_tender_open and nz_tender_search by referencing them as sources for the 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 clearly states when to use this tool: when you have an RFx ID from the sibling search tools. It does not explicitly list when not to use or provide alternative tools, but the context is clear and practical.

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 safe, idempotent, read-only behavior. The description adds that tenders are 'currently open' and lists included fields, providing useful context 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 concise sentences with front-loaded purpose. Every sentence adds value, no redundancy.

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

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

For a simple list tool with good annotations and full schema coverage, the description fully covers what the tool does, what it returns, and when to use it.

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

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

Schema description coverage is 100% with clear descriptions for 'limit' and 'query'. The description mentions an 'optional keyword filter' but adds minimal value beyond the schema.

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

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

The description uses a specific verb ('List'), resource ('currently open New Zealand government tenders from GETS'), and clarifies the scope. It distinguishes itself from web search and provides examples of tender types.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and gives clear usage context (New Zealand public procurement, RFPs, RFTs). It lacks explicit when-not-to-use guidance but is otherwise 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, openWorldHint=true, idempotentHint=true, destructiveHint=false, establishing a safe, read-only operation. The description adds valuable behavioral context: search scope (keywords applied to multiple fields), return fields (reference, title, agency, close date, region, categories, snippet, URL), and the fact that it returns a public URL. No contradictions with annotations.

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

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

The description is concise: three sentences covering purpose, examples, and return fields. It is front-loaded with the action and scope, with every sentence providing essential information. No filler or redundancy.

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

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

For a tool with 2 parameters, full schema descriptions, and no output schema, the description compensates by listing what the output contains. It explains the search scope and return fields adequately. The tool is simple (keyword search), and the description covers the key aspects a user needs to understand its behavior.

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

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

Schema coverage is 100%, with both 'query' and 'limit' having descriptions. The description adds that the query matches across multiple fields (titles, agency names, etc.) but does not add new technical constraints or formats beyond what the schema provides. The limit parameter's range and default are already in the schema. Thus, the description adds marginal value over the schema, meeting the baseline for high coverage.

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

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

The description clearly states it searches open New Zealand government tenders on GETS by keyword, specifies fields matched (titles, agency names, UNSPSC categories, regions, tender overview text), and provides example queries and return fields. This is a specific verb-resource combination that distinguishes it from sibling tools like nz_tender_detail (which likely retrieves detailed info) and nz_tender_open (which may list all open tenders).

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

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

The description explicitly states 'Use for questions like ...' providing clear context for typical queries (e.g., 'NZ government tenders for cybersecurity'). However, it does not provide explicit when-not-to-use guidance or mention alternative tools for more specific needs (e.g., nz_tender_detail for a known tender ID). This makes it slightly less than fully comprehensive, but still clear on intended use cases.

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

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

Annotations only indicate not read-only, not open-world, not idempotent, not destructive. The description adds critical behavior: rate-limited to 5 per identifier per day, free and not quota-counting, team reads digests, and the claim_token flow for retrieving status. No contradictions with annotations.

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

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

The description is longer than average but dense with necessary info: use cases, exclusions, token flow, rate limits. It is front-loaded with the primary purpose and structured logically. Every sentence contributes, though it could be slightly trimmed 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?

Despite no output schema, the description covers what happens on success (claim_token returned), how to follow up, rate limits, and the scope of feedback. It fully equips an agent to decide when to call and what to include, making it highly 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 covers 100% of parameters, so baseline is 3. The description adds value by explaining how to use claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and advising to describe issues in terms of Pipeworx tools/packs, not end-user prompts. This goes beyond schema definitions.

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

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

The description clearly states the tool sends feedback to the Pipeworx team about bugs, features, data gaps, or praise. It uses a specific verb ('Tell') and resource ('Pipeworx team'), and it explicitly distinguishes itself from sibling tools by limiting scope to Pipeworx connection tools only.

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

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

Usage guidance is explicit: '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 tells when NOT to use it (for tools from other MCP servers) and how to identify Pipeworx tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds caching behavior (5min-1h), data source (CF analytics-engine), privacy (no PII), and self-aggregating nature, going well 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?

The description is concise: one sentence for output, one sentence for use cases, one for technical details. Every sentence adds value with no repetition or fluff.

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

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

Given the simple read-only nature, one optional parameter, and no output schema, the description covers outputs, caching, privacy, and parameter effects completely.

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 one parameter with enum and description. The description adds meaning by explaining that shorter windows surface hot items and longer windows show steady-state demand, complementing the schema fully.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a window. The verb 'returns' and explicit outputs distinguish it from siblings like 'ask_pipeworx' or 'discover_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 three explicit use cases (discovering hot data sources, confirming canonical tools, aligning use cases). While it doesn't explicitly say when not to use, the context is clear and differentiated from 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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior; description adds critical behavioral details such as partition checks, semantic anchor, fill check logic, and response structure, without contradicting annotations.

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

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

Well-structured with clear sections (mode descriptions, semantic anchor, partition filter, fill check). Every sentence adds value, no redundancy or tautology. Appropriate length for the tool's complexity.

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

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

Comprehensive explanation of all behavioral aspects despite no output schema. Details response structure (opportunities[], partition_check fields, fill check results), threshold values (3pp, 0.30 Jaccard, 20% placeholder), and cross-reference to polymarket_fill_risk. Fully addresses 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?

Both parameters have schema descriptions, and the tool description adds extensive semantic value beyond the schema: explains usage modes, accepted input formats (slugs or URLs for event, seed questions for topic), and internal logic. High schema coverage (100%) with rich elaboration.

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

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

Clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. Distinguishes between three modes (trending_scan, event, topic) with specific details, setting it apart from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

Provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' Recommends event mode for specific markets and explains cross-event usage, giving clear contextual cues for the agent.

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 (readOnlyHint, idempotent) already indicate safe, deterministic behavior. The description adds extensive transparency: data sources (FRED, GDELT), model details, edge calculation, Kelly sizing, slippage handling, cache duration, and response diagnostics. Goes far beyond minimal requirements.

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?

Description is extremely long and dense, covering many details. While well-structured with sections and front-loaded purpose, the length may overwhelm some agents. Some details could be condensed without losing meaning.

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 9 parameters, no output schema, and nested response, the description covers all essential aspects: input parameters, response structure, segments, diagnostics, caching, and edge-case explanations. Nothing significant is missing.

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

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

Schema coverage is 100%, so each parameter has a description. The description adds value by providing defaults, examples, and additional behavioral notes (e.g., why min_kelly doesn't filter partitions, how to adjust slippage). This elevates understanding 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?

Clear statement of purpose: scanning Polymarket markets to find opportunities where Pipeworx data disagrees with market price. Good verb+resource. However, does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, which also deal with opportunities.

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 detailed context on when to use (for discovering betting opportunities), explains tradeable-edge knobs and why Fed bets are excluded. Lacks explicit 'when not to use' or comparison with alternatives, but the guidance is substantial.

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, etc.), the description discloses many behavioral traits: snapshots are written on cache-miss, gaps mean no scan, output includes tracked/expired/snapshot_dates, decay computed from daily closes, and 60-day TTL. This adds significant context beyond what annotations 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 detailed but front-loaded with the purpose. It is structured with arguments, response format, and limits. While every sentence adds value, it is somewhat dense and could be more concise, but given the complexity, it is well-organized.

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 fully explains the return format: tracked[] with full time-series, trend, decay; expired[] with lifespan; snapshot_dates[]. It also covers limits like 60-day TTL and data gaps. Complete for a telemetry tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the purpose of 'days' (lookback) and 'window' (snapshot family), and how snapshots are written on cache-miss. This goes beyond the schema's simple field descriptions.

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

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

The description clearly states the tool's purpose: tracking edge persistence and decay from daily snapshots. It uses a specific verb ('telemetry built from') and resource ('polymarket_edges snapshots'), and implicitly distinguishes from the sibling 'polymarket_edges' tool by focusing on historical 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?

The description provides a clear use case: answering 'how long has this edge existed and is it shrinking?'. It explains the output structure and limits, but does not explicitly state when not to use or compare with alternatives. The context implies usage for historical telemetry vs. raw edges, but 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?

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. Description adds behavioral details: walks the order-book ladder, returns verdict (clean|degraded|cannot_fill), warns that partial basket fills convert arb into directional position, and notes the dominant loss mode. 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?

Well-structured with clear sections for single-market and basket, uses bold for emphasis. Dense with information but slightly long; every sentence adds value. Front-loaded with purpose and requirements.

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 lists all return fields for both modes comprehensively. Covers edge cases (thin legs, forced directional risk, max clean notional). Fully explains what the tool returns and the implications.

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

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

Schema description coverage is 100%, but description adds significant value: explains side defaults and auto-detection for baskets, interprets size_usd as settlement notional for baskets, and clarifies the meaning of each parameter in context of the two modes. Provides usage constraints and clamps.

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 a realizable vs theoretical edge check against live order-book depth, with explicit single-market and basket modes. It distinguishes itself from siblings by specifying exactly when to use this tool (before acting on arb signals or edges trades above $500).

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: before acting on polymarket_arbitrage Sell/Buy-Every-Leg signals or polymarket_edges trades above ~$500. Implicitly advises against use for small trades. Names alternatives (polymarket_arbitrage, polymarket_edges) for context.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, so the bar is lower. The description goes well beyond that by explaining the token-overlap matcher, safety codes, pairing_unverified condition, gross vs net fee disclosure, skipped leg categories, and temporal alignment semantics. 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 very long, but every section earns its place given the tool's complexity and the lack of an output schema. It is front-loaded with the core purpose and modes, then flows into response, safety fields, and edge cases. Slight density and redundancy (e.g., repeated code lists) prevent a 5, but it is well-structured.

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

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

With no output schema, the description carries the full burden of explaining return values. It does so thoroughly: leg-by-leg prices, spread[].top_spreads_pp, compatibility_codes, per-entry flags, skipped_unclassified, temporal_alignment, fees_note, and counters. An agent gets everything needed to interpret the response 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% for all three parameters, so the baseline is 3. The description adds non-trivial semantics: how topic auto-fetches events, how explicit ticker/slug override the topic-mapped side, and that both modes run the identical matcher. It also lists examples, making the parameter semantics richer than 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?

Description states 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 by specifying the two venues and the comparison nature. The two modes (topic vs explicit) are also laid out immediately, so an agent can tell exactly what this tool does.

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

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

Provides clear context on when to use each mode: topic shortcuts for common macro events, explicit ticker/slug for custom pairings. Also warns that most pre-mapped topics return compatibility_warning today, so pre-mapped is not tradeable. However, it does not explicitly name sibling alternatives or when-not-to-use cases beyond the two modes.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds scope (anonymous IP, BYO key hash, account ID) and clarifies listing vs retrieval. No contradiction; adds meaningful context 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?

Three sentences with clear, front-loaded action. Efficient but could be slightly more concise. No wasted words.

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

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

Given the tool's simplicity (one optional param, no output schema), the description fully covers retrieval, listing, scoping, and pairing with siblings. No gaps for an agent to misuse.

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

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

Schema coverage is 100% and includes description for the single optional parameter. The description repeats the schema's 'omit to list all keys' but adds no new semantic detail. Meets baseline for high schema coverage.

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

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

The description clearly states the tool retrieves a previously saved value via 'remember' or lists all keys, with specific verb 'retrieve' and resource 'value previously saved via remember'. It distinguishes itself from siblings like 'remember' and 'forget' by explicitly mentioning pairing.

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 context for when to use: to look up stored context without re-deriving. Mentions scoping and pairing with remember/forget. Does not explicitly state when not to use or compare to other siblings beyond remember/forget, but guidance 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?

The description clearly discloses that setting mark_read:true mutates the read state of events, which is a behavioral trait. However, the annotations declare readOnlyHint=true, which implies no state mutation occurs. This contradiction reduces transparency, as the agent cannot rely on the annotations alone. The description adds some context beyond annotations (e.g., return structure) but is undermined by the inconsistency.

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

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

The description is concise (4 sentences) and front-loaded with the core purpose. Every sentence adds essential information without redundancy. The structure flows logically: purpose → return format → filtering → side effects → alternative access.

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 5 optional parameters and no output schema, the description adequately explains the return format (source, citation_uri, raw payload) and filtering behavior. It also mentions an alternative access method. However, it does not specify pagination behavior for large result sets beyond the limit parameter, which could be considered a minor gap for a polling tool.

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

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

The input schema already covers all 5 parameters with descriptions (100% coverage). The description adds value by explaining usage context, such as 'set mark_read:true to flag returned events read so the next call only shows newer ones', which goes beyond the schema's static description. It also reiterates key constraints like default limit.

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

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

The description opens with a specific verb-resource pair ('Pull fired events from your subscription feed') and details what is returned (source, citation_uri, raw payload). It clearly distinguishes itself from sibling tools like list_subscriptions or subscribe by focusing on reading alert data.

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

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

The description explains when to use the tool (to fetch recent alerts) and provides context for polling suitability. It also mentions an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts/dashboards. However, it does not explicitly state when not to use it relative to other 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 details the fan-out behavior to multiple sources, fallback logic (GDELT→GNews when rate-limited), soft-fail for USPTO, and return structure (structured changes grouped by source, total_changes count, 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?

Description is a single paragraph that is information-dense and front-loaded with purpose, but could be slightly more concise (120 words). Still very efficient.

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

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

Given the tool's complexity (multiple sources, fallback, parameter formats) and no output schema, the description covers all critical aspects: data sources, failure behavior, parameter semantics, return structure, and comparison with sibling tool. No gaps.

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

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

Schema coverage is 100% with clear descriptions, but the description adds extra value by explaining 'since' shorthand formats ('7d', '30d', '3m', '1y'), suggesting default '30d', and clarifying that 'value' can be ticker or zero-padded CIK.

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

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

The description clearly states the tool is a change feed for a company, aggregating from multiple sources (SEC EDGAR, GDELT→GNews, USPTO) in one parallel call. It explicitly distinguishes from sibling entity_profile by describing the static profile alternative.

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 example natural language queries ('What's new with X', 'latest on Y') and explicitly says when to use entity_profile instead for static profiles. Also gives advice on typical 'since' values ('Use "30d" or "1m" for typical monitoring').

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 idempotent hint and non-destructive behavior. The description adds valuable context about scoping by identifier and persistence duration (24h for anonymous, persistent for authenticated), which goes 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?

Three well-structured sentences, each earning its place. The purpose is front-loaded, and every sentence adds unique information without redundancy.

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

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

For a simple two-parameter tool with no output schema, the description provides complete context: what it does, when to use, how data is stored, and complementary tools. No gaps remain.

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

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

Schema covers 100% of parameters with descriptions. The description adds usage examples for keys (e.g., 'subject_property') and values, and explains the storage mechanism, adding meaning beyond schema.

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

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

The description clearly states the tool saves data for reuse, using specific verbs like 'save' and 'store'. It distinguishes from sibling tools like recall and forget by naming them and explaining their complementary roles.

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 when to use ('when you discover something worth carrying forward') and mentions complementary tools (recall, forget). It could be improved by adding explicit when-not conditions, but overall it provides clear guidance.

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

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

Beyond the readOnly/idempotent annotations, the description discloses graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), internal cascading lookups, and the behavior of unresolved identifiers ('stated explicitly under `unresolved` rather than omitted'). These are meaningful behavioral traits not present in the annotations.

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

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

The description is long but well-structured: examples, purpose, usage directive, then supported types and caveats. It is front-loaded and mostly dense with useful detail, though the long enumeration of identifier sources could be tightened without losing critical information.

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

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

With no output schema, the description fully covers return values for both types, input format requirements, unresolved identifier handling, and failure degradation. It even addresses edge cases like non-US issuers and non-ticker instruments. An agent has everything needed to call 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?

Although the schema already has 100% parameter coverage, the description adds substantial semantics by spelling out what each type resolves to (company: CIK, ticker, LEI, FIGI; drug: RxCUI, ingredient, brand) and by specifying input variants (ticker, CIK, ISIN, name; brand/generic). This goes well beyond the schema's brief 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 opens with concrete user-phrase examples and a clear statement: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It names a specific verb and resource, and distinguishes itself from siblings by positioning itself as the entry point for name-to-ID resolution.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' giving a direct when-to-use instruction. It also details accepted input forms per supported type and notes that the tool replaces 2-3 manual lookups, providing clear context for when to invoke it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context: probes each entity with ai_visibility_check, ranks by score, returns ranked list with score, confidence, signal density. 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?

Two sentences plus a quoted use-case. Every sentence adds value: purpose, mechanism, example, output format. No fluff. Front-loaded with key action.

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

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

With no output schema, the description adequately explains return values (ranked list with score, confidence, signal density). Covers purpose, usage, and behavior. Could mention the subject treatment (first entity) but schema covers it.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add new meaning beyond the schema; it integrates parameters into the narrative but doesn't provide additional syntax or constraints.

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

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

The description uses specific verb 'compare' and resource 'AI visibility across multiple entities'. It clearly distinguishes from sibling ai_visibility_check (single entity probe) by emphasizing side-by-side comparison and ranking.

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: 'Useful for competitive AI-marketing audits' with an example query. It implies use for multiple entities vs. single entity (ai_visibility_check) but does not explicitly state exclusions or alternatives.

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

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

Discloses composite nature (fans out across deps.dev and bundlephobia), partial failures (bundlephobia first measurement delay, sources_failed), and return structure (summary block, advisories, alternatives). Annotations (readOnlyHint, openWorldHint, idempotentHint) are not contradicted; description adds behavioral context 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?

The description is front-loaded with the core purpose and usage. The second paragraph is somewhat dense but each sentence adds value (output structure, limitations, alternative versions). Could be slightly more concise, but overall well-structured.

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

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

Despite no output schema, the description fully covers return structure (summary block fields, per-advisory detail, links, alternative versions) and edge cases (partial failures, timeouts). For a complex composite tool with multiple sources, this provides sufficient context for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by specifying scoped packages are accepted (e.g., @types/node) and that version defaults to latest published version. This provides clarity beyond the schema.

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

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

The description clearly states the purpose as a composite 'should I add this npm package' check, specifying the verb 'scan' and the resource 'npm package'. It distinguishes from siblings by explicitly limiting to NPM ecosystem and noting alternatives for other ecosystems via deps.dev.

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 agent asks is X safe / popular / small or what does adding lodash cost me'. Also specifies when not to use (NPM only) and gives alternative tool usage for other ecosystems.

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 annotations, disclosing the embedding model (BGE-base-en), window size (500-char overlapping), similarity metric (cosine), character limit (200K chars) with truncation behavior, and output features (character offsets for verification). 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 four sentences long, front-loaded with the core purpose, and every sentence adds unique information (use case, pairing, technical details, return value). No redundancy or 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?

Despite lacking an output schema, the description explains return values (passages with offsets and similarity scores) and covers all critical aspects: input constraints, embedding details, truncation behavior, and integration with sibling tools. It is fully sufficient for an agent to use correctly.

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

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

Schema coverage is 100%, but the description adds significant context: explains that 'text' should be already-fetched content, 'query' is natural language, and 'limit' controls top-N passages. It also provides example queries, which adds value beyond the schema's dry 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 it performs semantic search inside a fetched record, using a specific verb ('search') and resource ('source'). It distinguishes the tool's purpose from siblings by emphasizing it works on already-fetched text and saves context, which is unique among the listed 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 tells when to use the tool ('when the record is too big to cram into the prompt') and pairs it with ask_pipeworx_grounded. However, it does not explicitly state when not to use it or list all alternative tools, missing some exclusivity 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 contradicts the annotation idempotentHint=true by stating each call creates a new subscription with a new ID, implying non-idempotent behavior. Despite other disclosures, this inconsistency severely undermines transparency.

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

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

The description is efficiently packed with information in a single paragraph, front-loading the main action and return. While concise, it could be better structured (e.g., bullet points for types) for improved readability.

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

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

Given the tool's complexity (multiple subscription types, delivery channels, constraints), the description covers all important aspects: return value, prerequisites, type-specific parameters, delivery options including webhook technicalities, 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?

Even though schema coverage is 100%, the description adds significant meaning with concrete examples for each subscription type, detailed parameter formats, and delivery options with real constraints like phone verification and daily caps, going well 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 uses a specific verb 'Create' and explicitly names the resource 'proactive monitoring subscription'. It clearly states it returns a subscription ID, distinguishing it from sibling tools like 'list_subscriptions' or '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?

The description provides prerequisites (OAuth account), constraints (phone verification, daily SMS cap), and references to related tools (recent_alerts, GET endpoint). However, it does not explicitly contrast with alternatives or state when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, covering safety. The description adds context about what the tool returns (category-bucketed example questions) and that it draws from a live catalog of thousands of tools, without contradicting any annotations. However, it does not disclose any additional behavioral traits beyond what annotations and the return description imply.

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 trigger phrases and is well-structured, but it is somewhat verbose (multiple trigger phrases and a long list of categories). While every sentence adds value, it could be slightly more concise without losing clarity. Overall, it earns its length.

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

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

Given the tool's role as a discovery tool with many siblings, the description is complete. It explains the purpose, the return format (category-bucketed examples with tool+argument shapes), usage variants (no args vs topic), and when to use it. No output schema exists, but the description adequately covers the return value and context.

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% (one optional parameter with description). The description adds meaningful context: the topic parameter values (finance, pharma, etc.) and the default behavior when omitted (full spread). This goes beyond the schema's description of 'Optional focus area' by listing example values and the effect of omission.

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 the onboarding entry point for an agent to learn what questions to ask Pipeworx. It specifies it returns category-bucketed example questions with tool+argument shapes, and distinguishes itself from sibling meta-tools like ask_pipeworx and entity_profile by being the first tool to use when the agent doesn't know what Pipeworx can 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 explicitly provides when to use this tool: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also gives guidance on how to call it (with no arguments for full spread, or pass topic to focus) and mentions alternatives implicitly by referring to meta-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?

Discloses behavioral traits beyond annotations: ownership enforcement, deactivation vs deletion, and that historical events remain accessible via recent_alerts. 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?

Two sentences, front-loaded with action, no superfluous words. Every sentence adds 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?

For a simple tool with one parameter and no output schema, the description fully covers purpose, behavioral effects, and side effects. 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 covers the single 'id' parameter with description; the description adds that it's the id returned by subscribe, providing useful context beyond 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 'Cancel a subscription by id', identifying the specific verb (cancel) and resource (subscription), and it distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Specifies ownership enforcement and that the row is deactivated not deleted, providing clear context for when to use and what to expect. Could be more explicit about when not to use, but still gives strong guidance.

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

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

The description goes far beyond the readOnlyHint by detailing the two internal pipelines, the exact verdict enum, and the crucial caveat that 'could_not_verify' means the check did not happen and must not be treated as evidence. It also clarifies the 'unsupported' state, adding significant behavioral context beyond the annotations.

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

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

The description is long but densely informative, with no filler. It front-loads trigger phrases and purpose, then efficiently covers internal routing, return values, and error semantics. It could be slightly more compact, but every sentence earns its place.

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

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

Since there is no output schema, the description appropriately explains the return value structure including the verdict enum, citation, and reasoning. It also covers error and unsupported cases, making it complete for a tool of this complexity and read-only nature.

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 tool description does not add substantial meaning beyond the schema. It mentions the tolerance override and natural-language claim format, but these are already fully described in the input schema, so the description's contribution is marginal.

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 'natural-language claim verification against authoritative sources' and lists specific trigger phrases. It also distinguishes the financial vs. non-financial processing paths and notes it replaces multi-step pipelines, making its purpose unmistakable.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing for financial vs. other claims, but it does not explicitly name alternative sibling tools or state when not to use this tool, leaving some room for interpretation.

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