Google_search_console

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds behavioral context: free default model, BYO key for Anthropic, per-model return structure. No contradictions with annotations.

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

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

Three sentences covering purpose, default behavior, key option (apiKey), and output structure. Every sentence adds value; 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 4 params, no output schema, and strong annotations, the description fully explains inputs, default behavior, optional apiKey usage, and return format (per-model scores + combined view). No missing aspects.

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?

All 4 parameters have schema descriptions (100% coverage). Description adds meaning: default model ('workers-ai' free), '_apiKey' passed straight to Anthropic, 'context' disambiguates. Provides richer guidance than 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?

Uses a specific verb ('Probe') and resources ('LLMs for what they know about a business / brand / product / topic') with explicit outputs ('score visibility (0-100) per model'). Distinguishes clearly from siblings like 'scan_competitor_ai_presence' by focusing on AI knowledge scoring.

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?

States use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'). Explains default model (free) and when to provide '_apiKey' for Anthropic. Doesn't explicitly list when not to use, but context signals with similar tools like 'compare_entities' imply mutual exclusivity.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the internal routing/fill-arguments behavior, the return contract ('structured answer with stable pipeworx:// citation URIs'), and the fast/default-call trait. There is no contradiction with annotations, and no destructive/auth risk is hidden.

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

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

The description is dense and front-loaded with the most important selection rule ('PREFER OVER WEB SEARCH'), and every paragraph serves a purpose: domains, behavior, invocation cues, examples, and alternatives. It is longer than the high-bar example but the length is justified by its role as a default router; a few phrases like 'works on every tier' are slightly redundant.

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

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

With no output schema, the description compensates by specifying that results are 'structured answer with stable pipeworx:// citation URIs' and clarifies that breaking news is handled internally via news packs. It is complete enough for an agent to select and call it, though it does not detail the exact shape of citations or any no-result/edge-case handling.

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 all six parameters are aliases of a single natural-language question, so the schema already fully describes them. The description adds illustrative examples but no new semantic detail about the parameters themselves, keeping this at the baseline of 3.

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

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

The description names a concrete operation — route a factual question to one of 5,743 verified tool paths and return a structured, cited answer — and positions ask_pipeworx as the default entry point. It explicitly differentiates from siblings like ask_pipeworx_grounded and deep_research rather than merely repeating the tool name.

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

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

It gives precise triggering signals ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') and domain examples, and explicitly says when NOT to use it by naming alternatives: ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions. This is the clearest possible when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context: it's a full working router (not a fallback stub), no candidate is currently active so it matches ask_pipeworx exactly, and the experimental nature (routing differences come and go as candidates are tested). This transparency about current state is genuinely useful 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 somewhat long but information-dense and well-structured. It front-loads the beta identity, states the relationship to the sibling, and ends with a behavioral clarification that prevents misclassification. The 'No candidate is active right now' detail is important context that justifies the length.

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

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

The description is complete for an agent trying to decide whether to use this tool. It explains the experimental status, the fallback behavior (none — it's a full router), and how it relates to the stable ask_pipeworx. Without an output schema, the description could ideally explain the response shape more, but it does mention 'same response shape' as the stable tool, which is sufficient given the sibling relationship.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters (question plus five aliases). The description mentions 'same arguments' but doesn't add detail about how the question should be phrased. The schema does say natural language is accepted, so baseline 3 is appropriate — the description doesn't need to compensate.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router with the same tools, arguments, and response shape. It distinguishes it from the stable sibling by noting it's the experimental edge with candidate routing improvements. However, it doesn't explicitly state the core function of what ask_pipeworx does (answer questions by routing to 5,743 tools), relying on the sibling context.

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 it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It clarifies both when to use it (want newest routing) and implies when not to (need stable/proven behavior). This is strong usage guidance.

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

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

No contradiction with annotations; readOnly/openWorld/idempotent all match. Description adds substantial detail beyond annotations: extraction-only behavior, exact success and refusal return shapes, refusal reasons, and the extra LLM call cost.

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 dense but each clause adds distinct value: mode, mechanism, return contract, refusal reasons, use case, and cost tradeoff. It is front-loaded with the most important distinction and contains no filler.

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

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

Given no output schema, the description fully specifies the return value shape and refusal cases, which is essential for call correctness. It also covers cost, when to use, and relationship to ask_pipeworx, so nothing an agent needs to invoke it correctly 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?

Input schema covers 100% of parameters (all aliases of question), so the baseline is 3. The description doesn't add per-parameter details, but the schema already documents the aliases and natural-language question format. No compensation needed.

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

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

States a precise purpose: a grounded, hallucination-resistant answer mode that routes like ask_pipeworx but only extracts answers from tool results. This clearly distinguishes it from sibling tools, especially ask_pipeworx and ask_pipeworx_beta, by emphasizing evidence and refusal behavior.

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

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

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on' and lists high-stakes domains. It also provides the exclusion: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call cost, so an agent can decide between siblings.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds extensive behavioral context: fan-out process, response shapes, resolver contract, parent event extractor, news fallback, safety for low-confidence, closed markets, wide spreads, resolution-rule risk. No contradiction.

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

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

Description is very long and detailed, covering many edge cases. While comprehensive, it is verbose for a tool description. Front-loaded with purpose and usage, but overall length may hinder quick comprehension.

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 complexity (3 params, no output schema, many edge cases), description covers input formats, fan-out examples, response structure, safety, error states, and resolution rules. Almost all necessary context is provided.

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

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

Schema coverage is 100% with parameter descriptions. Description adds significant contextual usage details (examples, recommended default for include_raw, explanation of depth enum). Adds 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?

Description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, resolving the market, classifying, fanning out to category-specific data packs, and returning evidence and comparison. It differentiates from siblings by being specific to Polymarket bet research with full fan-out.

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

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

Explicit usage examples given: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Provides extensive fan-out examples per category. Does not explicitly state when not to use, but the context makes usage 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, openWorldHint, idempotentHint. The description adds behavioral details: data sources (SEC EDGAR/XBRL, FAERS), sorting by primary metric, and the efficiency claim of replacing 8–15 sequential lookups, which is useful 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 dense paragraph that front-loads query examples and key instructions. While not extremely concise, every sentence adds value; could be slightly more structured but effective overall.

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 2 parameters and no output schema, the description adequately covers data sources, sorting behavior, citation URIs, and performance benefit. It provides sufficient context for correct invocation without missing critical details.

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

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

Schema coverage is 100% (both parameters described). The description enriches understanding by giving concrete examples for 'type' (what data each pulls) and 'values' (tickers/CIKs for company, drug names), adding practical guidance 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's purpose: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It specifies distinct behaviors for company vs. drug types and contrasts with sequential single-pack lookups, making it unambiguous and differentiated from siblings.

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

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

The description explicitly recommends preference over sequential lookups ('ALWAYS PREFER over sequential single-pack lookups') and provides example queries. It lacks explicit when-not-to-use scenarios but clearly defines comparison context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds far beyond them: account/tier gating, parallel decomposition across 5,743 tools, gaps[] for unanswered facets ("never invented"), depth-dependent hop behavior, contradiction scans, citation_uri resolvability guarantees, semantic excerpting rather than head-truncation, and 15-90s latency expectations. No contradiction with annotations.

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

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

The description is long but earns its length: prerequisites are front-loaded first, then purpose, then routing guidance, then depth semantics, then return-format details, then latency. Every sentence carries operational meaning. It is not perfectly lean — depth semantics are partly duplicated from the schema's enum description, and the parenthetical-heavy density slows parsing — but for a tool with no output schema and two consequential parameter choices, the size is justified.

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

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

For a complex tool with no output schema, the description covers everything an agent needs to call it correctly: prerequisites and auth gating, return packet shape (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field), parameter semantics, sibling routing, latency expectations, and failure mode (empty gaps[] for non-catalog topics). Nothing essential is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value on top by defining what depth levels do behaviorally (standard re-angles unanswered gaps; thorough chases leads and adds contradictions) and by clarifying the question parameter accepts broad/multi-part natural language with concrete examples. The enum descriptions in the schema are already rich, so the added value is reinforcement rather than wholesale compensation.

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 and resource: "Grounded multi-source research across Pipeworx's 1500 STRUCTURED data sources... in ONE call." It explicitly distinguishes itself from siblings with "this is NOT open-web search" and contrasts its batch-decomposition behavior with ask_pipeworx's single LLM call. An agent can immediately tell what this tool is for.

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

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

Provides explicit when-to-use and when-not-to-use guidance: best for "broad/multi-part questions over structured data," with worked example questions. Routes away for "a single lookup," for "BREAKING or colloquial CURRENT-NEWS" topics, and for non-signed-in users, each naming ask_pipeworx as the alternative. This is model-tier routing guidance with no inference left to 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds useful behavioral context: returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and states 'each result is ready to call directly, no second schema lookup needed.' This 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?

The description is a single paragraph but packs purpose, domain list, output format, and usage guidance efficiently. It is front-loaded with the core action. However, it could benefit from clearer structure (e.g., bullet points) for quick scanning, losing one point.

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 explains the output (list of tools with schemas). It covers purpose, when to use, examples, and readiness to call. For a tool with 6 parameters (many aliases), the description provides sufficient context for proper use.

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 all parameters documented. The description mentions 'top-N' implying 'limit' but does not add new semantic meaning beyond the schema's field descriptions. Without additional clarification, the score is baseline 3.

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

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

The description starts with 'Find tools by describing the data or task' and lists specific domains (SEC filings, FDA drugs, etc.). It clearly identifies the tool as a meta-discovery tool that returns ready-to-call tools, differentiating it from sibling tools by advising 'Call this FIRST when you have many tools available and want to see the option set.'

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: 'Use when you need to browse, search, look up, or discover what tools exist for:' with examples. It also advises using it first for exploring options. However, it does not explicitly name sibling tools as alternatives or state when not to use it, which would strengthen guidelines.

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

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

Even with readOnlyHint and idempotentHint already set, the description adds substantial behavioral detail: it fans out across SEC, XBRL, USPTO, USAspending, FDA, DOL, GDELT→GNews, and GLEIF; notes that USPTO PatentsView is sunset and soft-fails; explains that empty sections mean 'no data,' not bugs; and states private companies return resolved:false with an explicit notes line. This fully manages agent expectations 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 long but dense, and nearly every sentence carries a distinct piece of information: input forms, source fan-out, field semantics, failure behavior, and fallbacks. It would benefit from bullet formatting for readability, but it is not padded; the length is justified by the tool's complexity.

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

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

With no output schema, the description bears the full burden of explaining what is returned. It lists all returned fields (cik, company_name, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, sources_used/failed), explains soft-fail conditions, and gives expected empty-section semantics. An agent has enough context to invoke the tool and interpret results.

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

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

The schema already covers both parameters (100% coverage), so baseline is 3. The description adds meaningful clarification: type values are accepted interchangeably, value may be a ticker, CIK, or company name, and name resolution happens via SEC EDGAR company-name match. This reduces ambiguity beyond the schema itself.

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

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

The description opens with concrete user phrasings ('Tell me about X', 'research Acme') and then states the core action: 'full cross-source profile of a US public company in ONE parallel call.' It clearly identifies the resource (US public company) and differentiates the tool from single-source SEC/XBRL/news lookups, so an agent can recognize when this is the right high-level profile tool.

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

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

The description gives an explicit usage rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies valid inputs and the private-company fallback. However, it does not name or exclude related sibling tools like compare_entities or resolve_entity, so the when-not-to-use guidance is incomplete.

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, indicating a safe delete operation. The description confirms the destructive action ('Delete') and adds context about clearing sensitive data, but does not provide additional behavioral details beyond the annotations.

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

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

Two sentences front-load the action and then provide usage guidance. No wasted 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 delete-by-key tool with full schema coverage and clear annotations, the description covers usage scenarios, pairing hints, and is complete enough. No output schema is needed for a deletion operation.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete.' The description does not add extra semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key,' using a specific verb (delete) and resource (memory by key). It distinguishes from sibling tools by mentioning 'Pair with remember and recall,' making the purpose precise.

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 use cases: 'when context is stale, the task is done, or you want to clear sensitive data.' It also suggests pairing with remember and recall, offering alternatives and context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds transparency by explaining the extraction process (fetches page, extracts title/description/key links) and output format, which goes beyond annotations without contradicting them.

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

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

The description is tightly written with two concise paragraphs: the first explains functionality and output format, the second lists use cases. No extraneous words, and the core action is front-loaded in the first sentence.

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 low complexity (2 parameters, no output schema), the description fully covers necessary context: what it does, what it produces, and common use cases. No gaps remain for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, with both 'url' and 'max_links' having clear descriptions. The tool description adds no additional parameter context beyond what the schema provides, so a 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 specific verb 'Generate' and resource 'llms.txt file' for any URL, distinguishing it from sibling tools like 'scan_competitor_ai_presence' which focus on auditing rather than file generation. The enumerated use cases further clarify its purpose.

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

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

The description provides explicit use case scenarios (e.g., getting a client's site indexed, drafting for own project, auditing a competitor), giving clear context for when to use. However, it does not mention when not to use or suggest 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 read-only, idempotent, non-destructive behavior. The description adds significant value by listing the specific return data (coverage state, last crawl, canonical, etc.) and the diagnostic purpose, going well beyond the annotations.

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

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

Two sentences, no wasted words. Front-loaded with the core purpose, followed by usage guidance. 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?

Given 3 simple parameters, no output schema, and rich annotations, the description fully covers what the tool does and returns. It mentions key result fields (coverage, crawl, canonical, mobile usability, rich-results) so agents understand the response shape. 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%, so baseline is 3. The description adds value by clarifying that siteUrl must match gsc_list_sites output and that inspectionUrl must belong to siteUrl, aiding correct parameter usage 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?

Description clearly states the tool inspects a URL's index status in Google, listing specific aspects (coverage, last crawl, canonical, mobile usability, rich-results). The verb 'inspect' with resource 'URL index status' is specific and distinct from sibling tools like gsc_list_sites or gsc_search_analytics.

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

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

Explicitly states 'Use to debug why a page is or isn't indexed,' providing a clear use case. While it doesn't explicitly list when not to use or alternatives, the context is clear and sufficient for the agent to decide.

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

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

Annotations already declare readOnlyHint and destructiveHint, so the safety profile is covered. The description adds that the tool returns 'last download time, warnings/errors, and indexed counts'. However, it does not mention pagination, rate limits, or the fact that only submitted sitemaps are listed.

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 no fluff. The first sentence clearly states functionality, the second states use case. Perfectly front-loaded.

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

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

Given the simple nature (1 param, rich annotations), the description covers the main purpose and output fields. It could be slightly more complete by mentioning the format or any limits, but it is sufficient for a straightforward listing 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% with a good description for siteUrl. The description adds no additional parameter information 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 verb 'list' and the resource 'sitemaps submitted for a property', including specific data fields. It distinguishes from siblings like gsc_list_sites and gsc_search_analytics.

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 specifies 'Use to audit sitemap health', giving clear context. It does not explicitly state when not to use or mention alternatives, but the sibling list provides 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 indicate readOnly and non-destructive behavior; the description adds that it returns permission levels, but does not detail the response structure. Still, it provides sufficient context for a simple list operation.

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: first states the core functionality, second provides critical usage guidance. No wasted words, front-loaded with 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 zero parameters and no output schema, the description covers the tool's purpose, usage context, and example outputs. No gaps are apparent.

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

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

There are no parameters, so the schema baseline is 4. The description adds no parameter info, but none is needed. It explains the purpose of the tool, not specifics of parameters.

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

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

The description clearly states the tool lists sites with permission levels and explicitly positions it as the first call to obtain siteUrl for other tools, distinguishing it from sibling tools like gsc_inspect_url and gsc_search_analytics.

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 'Call this first to get the exact siteUrl other tools need', providing clear when-to-use guidance and even including example siteUrl formats.

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 nature. The description adds modest behavioral context such as data lag (~2-3 days) as noted in the startDate schema description, but does not significantly extend 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 extremely concise, consisting of two sentences that front-load the core purpose and key usage. Every sentence provides 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?

Given the absence of an output schema, the description adequately specifies the returned metrics (clicks, impressions, CTR, average position) and grouping. It covers essential information for a moderate-complexity tool with good annotation support.

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 each parameter, so the description does not need to add much. The description provides high-level purpose but no additional parameter-specific semantics 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 it queries Search Console search-performance data (clicks, impressions, CTR, average position) grouped by dimensions. It provides specific use cases like 'top queries/pages last month' and explicitly links to gsc_list_sites for the required siteUrl format, distinguishing it from siblings.

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

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

The description gives clear usage scenarios (top queries/pages, organic CTR, ranking trends) and a prerequisite (siteUrl must be from gsc_list_sites). It does not explicitly mention when not to use this tool, but the context is sufficient for appropriate selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds value by specifying that only the caller's subscriptions are listed and that it returns specific fields like created_at and fire_count.

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, no wasted words. The most critical information (what it lists, what fields it returns, and when to use it) is front-loaded and 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?

For a simple list tool with one optional parameter and no output schema required, the description provides all necessary information: scope (caller's subscriptions), return fields, and usage recommendations. 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?

The schema fully covers the single optional parameter include_inactive with its description. The description's mention of 'active subscriptions' implicitly adds context for the parameter's effect, but does not provide additional syntax or format details 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?

Description clearly states the tool lists the caller's active subscriptions and specifies the return fields (id, type, etc.). It distinguishes itself from sibling tools like subscribe/unsubscribe by framing the purpose as reviewing before adding or finding an id to cancel.

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

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

Description explicitly tells when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context for usage, though it does not explicitly name alternatives like subscribe or unsubscribe.

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 declare non-readOnly, non-openWorld, non-idempotent, non-destructive, which provide no positive behavioral clues. The description compensates richly: rate limiting ('5 per identifier per day'), free usage vs quota, the claim_token flow ('returns a claim_token; pass it back later'), and the constraint of describing issues in terms of Pipeworx tools/packs. This is exactly the context an agent needs beyond schema.

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

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

The description is longer than the calibration high example, but each sentence serves a distinct purpose: purpose, when-to-use, exclusion, claim-token flow, rate limit, and cost. It is front-loaded with the core purpose and well-organized, though a bit dense. 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?

For a feedback tool with no output schema and sparse annotations, the description is fully self-contained. It explains what happens on filing (returns claim_token), how to later retrieve resolution status, rate limits, cost, and scope limitations. An agent has everything needed to select and invoke this tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful param semantics: it explains the claim_token is a 'pwfb_…' token and how to use it for reading status, and it gives message-content guidance ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This exceeds schema detail, warranting above baseline.

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

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

The description opens with a clear verb+resource statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It further distinguishes the tool from sibling ask/discover tools by enumerating exact feedback types (bug, feature, data_gap, praise) and stating it is ONLY for Pipeworx tools, not other MCP servers. This is specific and unambiguous.

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

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

The description provides explicit when-to-use triggers ('Use when a tool returns wrong/stale data', 'when a tool you wish existed isn't in the catalog') and a clear exclusion ('if the tool came from a different MCP server... file it with that server instead'). It even offers a fallback disambiguation ('Not sure? Pipeworx tool names are the ones this connection lists'). This is exemplary usage guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context: data is derived from CF analytics engine, no PII, cached 5min-1h, self-aggregating. 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 moderately concise, starting with the main purpose, then listing use cases in a bullet-like format, and ending with technical details. All sentences are informative, though slightly verbose in the use-case list.

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

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

For a simple tool with one optional parameter, the description covers purpose, usage, behavior, and return content (top tools, packs, volume). No output schema exists, but the description sufficiently describes the output structure.

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

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

The schema has 100% coverage with an enum and description for the window parameter. The description adds semantic guidance on choosing between windows based on intent (hot vs steady-state), improving on the schema-only information.

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 trending data (top tools, packs, call volume) based on other agents' usage. It distinguishes itself from sibling tools by focusing on aggregated trending signals rather than direct searches or entity profiles.

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

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

The description explicitly lists three concrete use cases (discovering hot data sources, confirming canonical tools, aligning use case) and provides guidance on selecting the window parameter ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). It lacks explicit when-not-to-use advice but gives sufficient 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?

The description goes far beyond the annotations (readOnlyHint, openWorldHint, etc.) by detailing internal algorithms (monotonicity, partition checks, semantic anchor, partition filter) and the fill check with realizable_edge_pp. It warns against trading when overround exists only at last-trade, providing complete behavioral 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 long but well-organized: it starts with the core purpose, then systematically describes each mode and key features. Every sentence adds value, though some technical details could be condensed. It avoids redundancy and is clearly structured.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly covers return fields (opportunities[], partition_check, fill_check) and cross-references polymarket_fill_risk for custom sizing. It answers likely agent questions about when to trade and how signals work.

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

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

The input schema already covers both parameters with descriptions (100% coverage). The description adds significant value by explaining acceptable formats (full URLs accepted for event, seed question examples for topic) and elaborating on their behavior, enriching the schema definitions.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific verbs and resources, effectively differentiating from siblings.

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

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

The description provides explicit guidance on when to use each mode, including recommendations (event for specific market). It implicitly covers when not to use alternatives by contrasting modes, but it could be more explicit about when to choose a sibling tool like polymarket_fill_risk (only mentioned for custom sizing).

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

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

Annotations already indicate read-only, idempotent behavior. The description adds extensive transparency: details on caching (1h at KV level), segment logic, edge calculation (slippage, Kelly caps), diagnostics for empty segments, and a warning about unreliable Fed data. 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 somewhat lengthy but well-structured with clear sections (model families, response structure, knobs, cache). Every sentence adds value, though verbosity could be trimmed for faster 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?

Given the tool's complexity (9 parameters, nested response segments, no output schema), the description covers return values, diagnostics, caching, and edge filtering comprehensively, ensuring agents can 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 coverage is 100% with each parameter described. The description provides additional context (e.g., tradeable-edge knobs) but does not add meaning beyond what the schema already conveys. 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 scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, distinguishing it from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on edge detection across multiple model families.

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 positions the tool for 'what should I bet on today' and provides explicit knobs for tuning (e.g., min_liquidity, max_spread_pp). It lacks explicit when-not-to-use guidance but offers clear context for typical usage and notes Fed bet exclusion.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral detail: it reads from daily snapshots, explains the response structure (tracked[], expired[], snapshot_dates[]), notes the 60-day TTL, and clarifies that decay numbers come from daily closes not intraday. No contradictions.

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

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

The description is front-loaded with the key question and is well-structured, but it is verbose with some details (e.g., the signed nature of edge_pp_net, expiration details). Every sentence adds value, but could be slightly trimmed 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?

With no output schema, the description compensates by thoroughly describing the response fields (tracked with time-series, trend, decay; expired with lifespan; snapshot_dates) and limits (TTL, snapshot start). It is fully adequate for an agent to understand what the tool returns.

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 descriptions for both parameters. The description adds value by confirming defaults (days default 14, max 30; window default '1wk'), listing explicit options for window ('24hr | 1wk | 1mo'), and noting clamping behavior. This goes slightly beyond the schema.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific question about edge longevity. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical time-series and trend analysis, not just current edges.

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

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

The description gives clear context on when to use (to evaluate if an edge is fresh or decaying) but does not explicitly state when not to use it or provide direct alternatives. The contrast between 'fresh wide edge' and '3-week-old wide edge' implies usage, 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 declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds significant behavioral context beyond this: it explains that the tool walks the ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and a verdict. It also highlights the danger of partial basket fills converting an arb into an unhedged directional position (the dominant loss mode). 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 relatively long but well-structured with bold headings for modes and key terms. Every sentence earns its place by explaining mode-specific behavior, return fields, or usage guidance. It front-loads the purpose and provides detailed behavioral information. Could be slightly more concise without losing clarity, but overall efficient for the complexity.

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

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

Given the tool's complexity (two modes, many return fields, no output schema), the description is remarkably complete. It lists all return fields with clear explanations, details parameter behaviors for each mode, and warns about pitfalls like thin legs and forced directional risk. No gaps are apparent.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds substantial value beyond schema: it explains the dual meaning of `size_usd` (max spend for buys vs target proceeds for sells in single-market mode; settlement notional in basket mode), default values, and clamps. It also explains the `side` parameter's auto behavior in basket mode. This goes 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 clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It specifies two distinct modes (single-market and basket), lists the return fields, and explicitly differentiates from sibling tools by stating 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' This provides strong purpose clarity and sibling differentiation.

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: before acting on arbitrage signals or trades above $500. It explains the risk of partial basket fills leading to unhedged directional positions, which implies when not to use it (i.e., avoid converting an arb into a directional bet without checking). While it names alternative tools (arbitrage, edges) and positions this as a prerequisite, it does not provide exhaustive when-not examples. Nevertheless, the usage guidance is strong and context-rich.

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

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

Annotations already mark it readOnly/idempotent/non-destructive, and the description layers substantial behavior on top: matching is token-overlap not a shared resolution source, unknown metric_type/match_subtype legs are never paired, temporal_alignment null semantics, and Kalshi fees are not modeled. It also flags conditional disclosures ('BOTH can be non-empty on returned pairs, so read them even when matched_pairs>0'). No contradiction with annotations.

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

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

The description is long but earns its length: it has no filler and every block (response, safety fields, codes, fees, skipped counters) carries a distinct operational warning. It front-loads the core purpose and then uses labeled sections. A few repetitions (e.g., temporal_alignment_unknown appears twice) mean it is not maximally tight.

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 contract documentation and does so thoroughly: response shape, safe-vs-warning fields, per-entry flags, null semantics, fee grossness, and skipped leg counters are all specified. An agent has enough to interpret results and know when a spread is not tradeable.

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

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

Schema already covers all three parameters 100%, including examples and override notes. The description adds useful interaction semantics – both modes run the identical token-overlap matcher and explicit ticker/slug override the topic-mapped side. This earns a bit above baseline, though much of the parameter meaning is already in the schema.

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

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

Opens with a specific verb+resource: computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It names the two venues and the core output (top_spreads_pp, Kalshi − Polymarket), which clearly distinguishes it from the other polymarket_* siblings. The two-mode explanation also makes the purpose concrete.

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 distinguishes the `topic` shortcut mode from the explicit `kalshi_event_ticker` + `polymarket_event_slug` mode, so an agent knows how to choose inputs. It gives honest when-not-to-trust guidance ('Real cross-venue spreads are rarer… pre-mapped ≠ tradeable', spread_pp is gross not net). It does not, however, name sibling alternatives like polymarket_arbitrage or state when to prefer them, which keeps this at 4 rather than 5.

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

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

Adds context about scoping to identifier and pairing with other tools, enhancing the already clear annotations (readOnlyHint, idempotentHint). No contradiction.

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

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

Two sentences, front-loaded with action verb, every sentence provides essential information without waste.

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

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

Given low complexity (one optional param, read-only, no output schema), the description covers purpose, usage, behavior, and relationships to siblings fully.

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 parameter description. Description reinforces meaning and adds context about listing keys when omitted, earning above baseline.

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

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

The description clearly states it retrieves values saved via remember or lists keys, using specific verbs and distinguishing from siblings remember and forget.

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

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

Explicitly explains when to use (retrieve stored context) and when to omit key (list all). Provides pairing guidance with remember/forget.

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

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

Annotations already mark the tool as read-only and idempotent, but the description adds important behavioral details: the mark_read parameter affects future calls, and the feed is also accessible via a direct GET endpoint. 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 concise at three sentences, front-loaded with the core purpose, and each sentence provides necessary 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 tool with 5 optional parameters and no output schema, the description covers return format, filtering, mark_read behavior, and alternative access, making it fully actionable for an agent.

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

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

The description explains key parameters (type, since, mark_read) beyond the schema, and adds context about return fields (source, citation_uri, payload). With 100% schema coverage, the description still adds significant value.

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

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

The description starts with a clear verb and resource ('Pull fired events from your subscription feed'), specifying exactly what the tool does. It distinguishes from sibling tools like list_subscriptions by focusing on retrieving fired events rather than managing subscriptions.

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

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

The description states that polling works fine and mentions an alternative GET endpoint for scripts/dashboards, providing usage context. However, it does not explicitly compare with siblings 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, idempotentHint, openWorldHint, and no destructive hint. The description adds behavioral context: fans out to three sources, GDELT preferred with GNews fallback, USPTO soft-fail until reactivated. No contradiction with annotations.

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

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

The description is a single dense paragraph that front-loads the purpose with example queries. It covers all key aspects but could be better structured for readability (e.g., bullet points). Still highly informative without waste.

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

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

Despite no output schema, the description explains return format: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'. It covers purpose, parameters, sources, fallbacks, and sibling differentiation, making it complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions. The description adds value by explaining 'since' accepts ISO date or relative shorthand with examples ('7d', '30d', '3m', '1y'), clarifying 'value' can be ticker or CIK, and noting 'type' only supports 'company'.

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

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

The description clearly states it is a change feed for a company, aggregating SEC filings, news, and patents. It provides specific example queries ('what's new with X') and explicitly distinguishes from sibling tool 'entity_profile' for static profiles.

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 explains when to use (e.g., 'latest on Y', 'updates on Acme') and when not to ('Use entity_profile instead when you want the static profile'). It details fallback logic (GDELT→GNews) and acknowledges limitations (USPTO soft-fail), providing explicit guidance.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. Description adds useful storage scope (key-value, user identifier) and retention details (persistent vs 24h). 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?

Single well-organized paragraph: purpose, usage guidance, storage details, pairing hints. Every sentence adds value, though could be slightly 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?

Tool is simple with 2 params and no output schema. Description completely covers purpose, usage, storage behavior, and pairing with sibling tools. 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 description coverage is 100%, so baseline 3. Description reinforces key-value pair concept but adds no new parameter semantics beyond examples already in 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?

Clearly states 'Save data the agent will need to reuse later' — specific verb+resource. Distinguishes from sibling tools 'recall' and 'forget' by name.

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

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

Explicitly says 'Use when you discover something worth carrying forward' with examples. Provides when-not-to-use advice and directs to alternatives: 'Pair with recall to retrieve later, forget to delete.'

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

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

The annotations already mark it read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral details: ambiguous matches return figi_candidates rather than asserting, unresolved identifiers are explicitly listed, enrichment degrades gracefully when upstream sources are down, and identifiers carry provenance labels.

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

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

The description is dense and monolithic, but it is front-loaded with examples and purpose, and nearly every clause adds operational guidance. It could be better formatted with bullets, but the information density justifies the length for a tool with this complexity.

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

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

Despite no output schema, the description explains return contents (CIK, ticker, LEI, ownership, FIGI, RxCUI, citation), edge cases (ambiguous instruments, unresolved identifiers), and graceful failure modes. An agent has enough context to select and invoke the tool correctly across both supported entity types.

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

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

Schema coverage is 100%, but the description goes well beyond it: it explains that company input can be a ticker, CIK, ISIN, or name, gives examples, and warns to pass the entity name only—especially for bonds where trailing security-class words will fail the FIGI lookup. This materially improves correct parameter construction.

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 example queries and a clear verb-resource pair: resolve a user-spoken NAME to canonical identifiers that other tools require as input. It differentiates itself from entity_profile, compare_entities, and search_within by scoping to identifier lookup rather than profiling or comparison.

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

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

It explicitly instructs 'Use FIRST whenever you have a name but need an ID,' and details the supported entity types and input forms. It does not explicitly name alternatives or state when not to use the tool, but the 'use first' guidance plus type coverage gives clear practical routing.

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

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

Annotations already indicate safety (readOnly, idempotent, non-destructive). Description adds how it probes via ai_visibility_check, ranks, and returns score/confidence/signal density per entity, disclosing behavior 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: purpose, mechanism, use case with output details. Front-loaded, no fluff.

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

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

With no output schema, description fully explains return format (ranked list with score, confidence, signal density). Covers all parameters and their roles. Complete for the tool's complexity.

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

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

Schema has 100% coverage with descriptions. Description adds value by specifying the first entity is 'subject' for narrative and rest are competitors, and default model is 'workers-ai'.

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 compares AI visibility across entities side-by-side, distinct from sibling ai_visibility_check (single entity) and compare_entities (generic). Uses specific verb 'compare' and resource 'AI visibility', with details on ranking and scores.

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

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

Provides clear context for competitive AI-marketing audits and example question. Implies single-entity checks via ai_visibility_check, but lacks explicit when-not-to-use or alternatives list. Still guides usage well.

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?

Description discloses important behavioral traits beyond annotations: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and the 'sources_failed' list will indicate timeouts. Annotations already declare readOnly and idempotent, so description adds context on latency and partial success.

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 that front-loads the purpose and then adds usage, return details, limitations, and behavior. It is informative but not excessively long; each sentence adds value. Minor redundancy could be trimmed, but overall well-structured.

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

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

Given no output schema, the description fully explains the return value structure: summary block fields, per-advisory details, links, and alternative versions. It also covers edge cases like scoped packages, partial failures, and ecosystem limitation. Everything needed for an agent to understand the tool is present.

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 descriptions for both parameters. Description adds meaningful context: scoped packages are accepted for the 'package' parameter, and 'version' defaults to latest when omitted. This goes slightly beyond the schema alone.

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

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

The description clearly states the tool's purpose as a composite check for npm packages, combining deps.dev and bundlephobia data. It specifies the exact verb 'check' and resource 'npm package', and distinguishes from siblings by noting it's NPM-only in v1.

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

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

Explicitly says when to use: for questions like 'is X safe/popular/small' or 'what does adding lodash cost me'. Also gives a clear exclusion: for other ecosystems, use deps.dev:version directly. This provides clear guidance on when and when not to use.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), description reveals embedding model (BGE-base-en), chunking (500-char windows), similarity metric (cosine), and input cap (200K chars with truncation flag).

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

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

Four dense, front-loaded sentences with no filler. Every sentence adds value, from purpose to technical details to usage guidance.

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

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

Despite no output schema, description explains return format (top-N passages with offsets and similarity scores), making behavior fully predictable.

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

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

Schema has 100% coverage. Description adds examples for query parameter, details text truncation behavior, and specifies limit range, enhancing understanding beyond the schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource. It distinguishes from sibling tools like ask_pipeworx_grounded, which operates on the whole document.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded, providing clear context for when and how to use.

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

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

Annotations indicate readOnlyHint=false (write), idempotentHint=true, destructiveHint=false. Description is consistent and adds context about OAuth requirement, delivery caps, and verification steps. No contradictions.

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

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

The description is dense but well-structured, starting with main purpose, then prerequisites, types, and delivery channels. It is front-loaded and contains valuable information, though slightly lengthy.

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 (3 params, nested objects, no output schema), the description is thorough. It covers types, delivery channels, authentication, limits, and includes examples. Return value (subscription id) is mentioned.

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

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

Schema coverage is 100% with parameter descriptions. The description elaborates on each type and delivery option with examples, adding significant value beyond the schema. For nested objects like params and delivery, it provides detailed structures and 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 clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It distinguishes from sibling tools like list_subscriptions, unsubscribe, recent_alerts, etc.

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 specifies when to use (to subscribe to alerts) and prerequisites (requires Pipeworx OAuth account, anonymous/BYO cannot persist). It provides types and delivery channels but does not explicitly state when not to use or mention alternatives, though implied by sibling context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds behavioral context: call with no arguments for full spread, or with topic to focus. No contradictions, and it enriches understanding of how the tool behaves 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?

Description is detailed but front-loaded with common user queries. It efficiently conveys purpose, usage, parameter behavior, and output. Slightly long but every sentence adds value; concise for the amount of 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?

For an onboarding meta-tool with 1 optional parameter and no output schema, the description fully covers return values (category-bucketed example questions) and use-case. Annotations cover safety. No gaps given the tool's simplicity and role.

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

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

Schema coverage is 100%, and the parameter description in the schema matches the tool description ('Optional focus area: finance | pharma | ...'). The description does not add meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

Description clearly identifies the tool as the onboarding entry point for asking about Pipeworx's capabilities. It specifies the verb (returns example questions), the resource (category-bucketed examples with tool+argument shapes), and distinguishes from sibling tools like ask_pipeworx by emphasizing its role in learning what to ask.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Provides clear context for when to use, though no explicit when-not-to-use or alternatives beyond its own focus.

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 complements annotations by clarifying that the operation is a write (non-readOnly), idempotent, not destructive (row deactivated), and enforces ownership, adding 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?

Three concise sentences with no fluff, front-loaded with the core action and immediate additional details.

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

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

Given simple operation with one parameter, the description fully covers purpose, behavioral effects, and side effects (historical retention), meeting completeness needs.

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 description for 'id' parameter. Description doesn't add additional semantics beyond what schema provides, so baseline 3 is appropriate.

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

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

The description states 'Cancel a subscription by id' with clear verb and resource, and distinguishes from siblings 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?

Explicitly states ownership enforcement and that the row is deactivated, not deleted, so historical events remain available via recent_alerts, providing clear when-to-use and when-not-to-use 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?

Despite annotations already marking readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds crucial behavioral nuance: it explains the meaning of 'could_not_verify' (check did not happen, carries verification_error, must NOT be shown as evidence) versus 'unsupported' (no source covers it). This is exactly the kind of edge-case behavior that would be invisible without explicit disclosure and prevents a caller from misusing the result.

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

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

The description is dense yet well-structured, with an opening trigger list, a clear use-case sentence, a pipeline overview with routing rules, a verdict list, and a critical caller warning. Every sentence adds operational value; the IMPORTANT section is appropriately emphasized. Length is justified by the tool's complexity.

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

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

The tool handles two distinct verification pipelines, multiple verdict classifications, and has ambiguous failure modes. The description covers routing, evidence citation format, verdict semantics, and the critical could_not_verify vs unsupported distinction. With a rich input schema and clear annotations, there are no major gaps that would leave an agent guessing about return behavior or usage constraints.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds value by explaining what the default tolerance behavior is ('implied by wording, capped at 5') and when to override it (hallucination detection with 1–2). It also orients the 'claim' parameter with examples in the schema, so the description's added practical guidance is meaningful but not exhaustive.

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 multiple natural-language trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…') and states a specific verb+resource: 'natural-language claim verification against authoritative sources.' It clearly distinguishes this from sibling research tools by focusing on verifying a claim's truthfulness, not general research or entity lookup.

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 whenever the agent needs to check whether something a user said is factually correct.' It further differentiates two paths — structured SEC EDGAR for company-financial claims and a grounded pipeline for any other factual claim — and notes that it 'replaces 4–6 sequential calls (NL parsing → entity resolution → data lookup → comparison).' This gives the agent clear when-to-use and what-alternatives-it-replaces context.

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