Conceptnet

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

Annotations declared readOnlyHint, openWorldHint, idempotentHint, destructiveHint – so safety is clear. The description adds behavioral context: default model is free, Anthropic requires BYO key, return structure includes per-model {score, confidence, signals, raw_response} + combined view. 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?

Three sentences: core function + scoring, model/cost detail, and return/usages. Front-loaded with key info, no redundancy, 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?

Despite no output schema, the description details return structure (score, confidence, signals, raw_response + combined view). Parameters are fully described in schema (100% coverage). The description is sufficient for an agent to understand 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% – each parameter already has a clear description. The description adds minimal extra meaning (e.g., scoring range 0-100, purpose of context). Baseline 3 is appropriate as schema covers parameters adequately.

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 probes LLMs for brand visibility and scores 0-100 per model. It distinguishes from sibling tools like ask_pipeworx (general Q&A) and scan_competitor_ai_presence (similar but sibling name suggests broader scan), making its specific purpose evident.

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 identifies use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It mentions default vs BYO key for Anthropic, but does not explicitly contrast with sibling alternatives or say when not to use it, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, which cover the safety profile. The description adds meaningful context beyond annotations: it routes to a large tool network, fills arguments, returns structured answers with citation URIs, and works on every tier. It doesn't contradict the annotations, and the added behavioral detail (citations, single fast call) is useful.

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

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

The description is longer than average but every sentence earns its place: it begins with the most critical directive (PREFER OVER WEB SEARCH), provides a compact list of example queries, and ends with escalation guidance. The structure flows from when to use, to what it returns, to when to use alternatives. It is somewhat lengthy, but that length is justified given the tool's central role as an entry 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?

There is no output schema, so the description correctly explains the return format: structured answer with stable pipeworx:// citation URIs. It covers diversity of inputs, domain coverage, and alternatives, making it fully self-sufficient for an agent to decide when and how to call this tool. For a tool with this complexity, nothing important is missing.

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

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

The schema covers 100% of the parameters, with aliases documented and required question field. The description complements this by giving examples of valid questions and explaining the expected semantics: natural-language factual queries about real-world entities, events, or numbers. This elevates the parameter semantics from mere schema definitions to practical usage guidance.

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 specific verb ('routes', 'returns') and resource (5,462 tools across 1,419 verified sources) with clear scope: factual questions about real-world data. It explicitly distinguishes this tool from siblings like ask_pipeworx_grounded and deep_research, and provides concrete examples covering a wide range of domains. This is far above a simple 'ask' definition.

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 opens with an explicit directive to prefer this over web search, then lists when to use it ('what is', 'look up', etc.) and when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for multi-part questions). It even clarifies that breaking-news is already covered. This is model usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond these: beta status, live candidate routing that may change behavior, current inactive candidate state, and reassurance that it is a fully working router rather than a fallback. This is useful and does not contradict annotations.

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

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

The description is concise and well-structured, with four sentences that each add important information: what it is, its current state, when to use it, and its operational nature. There is no fluff or redundancy, making it highly efficient.

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

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

Given the tool's complexity (universal router with thousands of tools) and the presence of comprehensive annotations, the description covers key aspects: purpose, relationship to the stable version, current behavior, and safety profile. It does not detail the exact response shape, but it explicitly states it matches ask_pipeworx, which is sufficient. Minor gaps include not elaborating on what 'routing improvements' entail.

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 six aliases for the question parameter fully described. The description does not add any additional parameter semantics beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description clearly states the tool is a beta version of ask_pipeworx, a universal router, with explicit details on its scope (same 5,462 tools, same arguments, same response shape). It distinguishes from the sibling ask_pipeworx by noting it enables candidate routing improvements, making its unique purpose immediately clear.

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

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

It explicitly says to use it 'exactly like ask_pipeworx when you want the newest routing' and contrasts it with the stable router. However, it does not explicitly state when not to use it or provide explicit exclusions, though the beta label implies caution.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses the exact success return shape {answer, evidence, confidence, source, fetched_at, refusal_reason:null} and all refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). It also reveals the cost tradeoff (one extra LLM call), which annotations do not capture.

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: purpose first, then routing/behavior, then return/refusal format, then usage guidance and cost. Every sentence carries operational weight, though it is slightly long — a minor trim would earn a 5.

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

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

With no output schema, the description fully covers success and refusal return shapes, gives explicit usage boundaries, names the alternative, and details routing behavior. It is remarkably complete for a tool of this complexity.

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

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

Schema description coverage is 100% — every parameter (including aliases) is described as 'Your question in natural language.' The tool description does not add parameter-specific detail beyond this, so it meets the baseline but does not exceed it.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' which clearly identifies the tool's purpose as a grounded Q&A tool. It distinguishes itself from the sibling ask_pipeworx by emphasizing that it extracts answers only from tool results, making the specific value proposition unambiguous.

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

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

Explicit guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on... must not invent facts' and 'prefer ask_pipeworx for casual lookups.' This directly states when to use this tool, when not to, and names the alternative (ask_pipeworx).

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?

Disclosures go far beyond annotations: resolver contract (match confidence, alternatives), parent event extractor, news fallback fields, safety short-circuits, closed market handling, wide spread illiquidity, and resolution-rule risk. No contradiction with annotations (readOnlyHint: true, openWorldHint: true, idempotentHint: true, destructiveHint: false).

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

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

The description is lengthy but every section adds unique information: core purpose, classifiers, fan-out examples, response shapes, resolver contract, parent event extractor, news fields, safety, and resolution rules. It is well-structured with clear headings, justifying its length for a complex tool.

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

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

Covers all aspects: input format, output shape (with key fields), edge cases (closed markets, low confidence, wide spreads, resolution rules), and behavioral details. No output schema exists, but response shapes are described in sufficient detail.

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?

With 100% schema coverage, the description adds meaning: explains how 'market' interprets slug/URL/question text, how 'depth' controls quick vs thorough fan-out, and how 'include_raw' affects response size. This is valuable context 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 researches Polymarket bets by pulling Pipeworx data, accepts multiple input formats (slug, URL, question text), and returns an evidence packet with comparison. It distinguishes itself from sibling research tools by focusing on Polymarket bets and mentioning Pipeworx.

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

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

Provides explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and detailed examples of fan-outs. Does not explicitly list when not to use or alternatives, but the guidance is strong and contextually 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 (readOnlyHint, openWorldHint, idempotentHint) already indicate safe, repeatable behavior. The description adds substantial context: data sources (SEC EDGAR/XBRL, FAERS, FDA, ClinicalTrials), specific financial metrics, handling of off-calendar fiscal years, sorting by primary metric, and citation URI format. 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 a single paragraph that packs extensive information. It is front-loaded with example queries and includes necessary details. While dense, it is still relatively concise for the complexity, though minor restructuring could improve readability.

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

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

Given the tool's complexity (two entity types, diverse data sources, sorting, citations) and the lack of an output schema, the description is remarkably complete. It covers return format (paired data + citation URIs), sorting behavior, and edge cases (off-calendar fiscal years), leaving no major 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%, but the description adds richness beyond the schema: for 'type', it explains data sources and metrics; for 'values', it gives concrete examples (tickers/CIKs, drug names) and constraints. This significantly aids parameter understanding.

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

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

The description clearly states the tool does side-by-side comparison of 2-5 companies or drugs. It provides example queries like 'Compare X and Y' and explicitly distinguishes from sequential lookups, making the purpose unambiguous.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving strong usage guidance. It also details when to use each type (company vs drug) and what data to expect, though it doesn't mention when not to use or alternatives.

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

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

Annotations already declare readOnlyHint/openWorldHint/idempotentHint, and the description adds substantial behavioral context: account/paywall requirements, parallel decomposition into 5,462 tools, gaps[] never invented, citation_uri always fetchable, semantic excerpting, contradictions[] behavior, and timing (15-60s, thorough up to ~90s). 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 (several paragraphs) but well-structured: starts with the most critical caveat (ACCOUNT REQUIRED), then core functionality, then usage examples, then alternative tools, then depth details, then output format, then performance. Every section carries useful information, though some details (like depth semantics) are repeated in the schema, making it 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?

Given no output schema, the description compensates by thoroughly explaining the findings packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[], contradictions[], hop field, and citation_uri fetchability. It also covers authentication, payment, timing, and alternatives. This is comprehensive for a complex orchestrator 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 already covers both parameters with 100% coverage, but description adds enrichment: depth meanings are expanded in the body (quick=3 facets single hop, standard=5 default with gap-recovery + contradictions, thorough=8 paid with iterative hop) and the question parameter gains context about broad/multi-part suitability. The "thorough needs a paid plan" caveat adds practical parameter-dependent guidance.

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

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

Description clearly states it performs "Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources" in ONE call, with a specific verb and resource. It also distinguishes itself from siblings by noting "this is NOT open-web search" and contrasting with ask_pipeworx for single lookups, plus concrete examples like "compare X and Y's regulatory + financial exposure".

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 "Best for broad/multi-part questions over structured data" and provides direct when-not-to-use guidance: "For a single lookup use ask_pipeworx" and "For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx". Also handles authentication edge case: "If you are not signed in, use ask_pipeworx instead".

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=true, idempotentHint=true, destructiveHint=false, which are consistent with a discovery tool. The description adds that results are 'ready to call directly, no second schema lookup needed,' providing useful behavioral detail 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 but front-loaded with the core purpose. The list of domains could be trimmed, but it effectively communicates scope. Overall, it is well-structured and informative without excessive verbosity.

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 compensates by detailing the return value (names, descriptions, schemas with examples). It covers the main usage scenario and provides examples. Minor gaps (e.g., no error handling details) but sufficient for a discovery tool.

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

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

Schema coverage is 100% with good descriptions. The description adds value by explaining that the query parameter accepts aliases (task, q, search, description) and provides examples (e.g., 'analyze housing market trends'). This goes 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: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, etc.) and explains the output: top-N relevant tools with names, descriptions, and schemas. This clearly distinguishes discover_tools from siblings like 'query' or 'lookup' which are for direct data retrieval.

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 advises to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also specifies use cases (browse, search, look up) and domains. While it doesn't explicitly say when not to use it, the context is clear.

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

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

Discloses specific behaviors: returns data from multiple sources, mentions USPTO API sunset with soft-fail, and states it fans out in one parallel call. Annotations already indicate safe read-only behavior, and the description aligns without contradiction.

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

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

The description is information-dense but well-structured with example queries and a clear breakdown of returned data. Slightly long but every sentence adds value; could benefit from bullet points for readability.

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

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

Despite no output schema, the description comprehensively explains all returned data fields, their sources, and limitations (e.g., patents sunset). Covers enough context for correct tool invocation without needing additional documentation.

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?

Adds meaning beyond schema by clarifying that 'value' accepts ticker or zero-padded CIK and explicitly states names are not supported, directing to resolve_entity. Schema coverage is 100%, so the extra guidance is valuable.

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 a 'full cross-source profile of a US public company' with example queries and specific data sources. It distinguishes from siblings like resolve_entity by noting that names are not supported.

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 advises 'ALWAYS PREFER over chaining single-pack lookups for a holistic view' and directs users to resolve_entity if they have only a name. Provides clear context for when 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 indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data, which is beyond annotations. However, it doesn't specify behavior when key is missing, but the idempotent hint implies safe repeated deletion.

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

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

The description is two sentences with the action stated first. It includes purpose, use cases, and pairing, all in concise language with no wasted words.

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

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

Given the simplicity of the tool (one parameter, no output schema), the description covers purpose, usage, and context within the sibling tools. It lacks return value specification but the destructive annotation and idempotent hint provide sufficient guidance.

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

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

The input schema has 100% coverage with a description of the 'key' parameter as 'Memory key to delete'. The description simply repeats 'by key' without adding new meaning or examples, so 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 explicitly states 'Delete a previously stored memory by key', which is a specific verb+resource. It also distinguishes from siblings 'remember' and 'recall' by its action.

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

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

The description provides specific scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. It also mentions pairing with remember and recall, guiding when to use this tool in the context of the memory system.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description explains the internal steps: fetches the page, extracts title/description/key links, and emits standard markdown format. This adds significant behavioral context that annotations alone do not provide.

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

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

Two concise sentences with a bulleted usage list. Every sentence earns its place, front-loaded with the primary action. No wasted words.

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

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

Given no output schema, the description explains the output format (single text blob, standard markdown). Parameter count is low. Missing error handling or edge cases (invalid URLs), but overall adequate for a straightforward 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 two parameters well-described in the schema. The description mentions 'fetches the page' (implied url) and 'maximum number of link entries' (max_links), but does not add extra semantics beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for a URL, specifying the exact resource and action. It distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence, which address related but distinct use cases.

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

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

The description provides explicit use cases (client site indexing, personal project, competitor audit) but does not mention when not to use this tool or suggest alternatives. It offers clear context but lacks exclusionary 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 and destructiveHint=false, indicating a safe read. The description adds that it returns specific fields (id, type, etc.), which is useful but not critical. No contradictions.

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

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

The description is two sentences: first states purpose and return fields, second gives usage context. Every sentence adds value, with no wasted words.

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

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

Given no output schema, the description lists the return fields (id, type, etc.), which is helpful. It does not explain field meanings or pagination, but for a simple list of subscriptions, this is adequate.

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 fully documents the single parameter 'include_inactive'. The description does not add extra meaning beyond what the schema provides, earning 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 clearly states the verb 'list' and resource 'subscriptions', specifying 'the caller's active subscriptions'. It differentiates from sibling tools like 'subscribe' and 'unsubscribe' by focusing on listing.

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: 'Use this to review what you're monitoring before adding more or to find an id to cancel'. This tells when to use it and implicitly suggests alternatives (subscribe, 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 clearly indicate the tool is read-only, idempotent, and non-destructive. The description adds minimal behavioral context (e.g., 'edges'), but nothing contradictory.

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 short (one phrase), which is concise but lacks structure and clarity. It could benefit from a clearer sentence without being overly verbose.

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 six parameters and the knowledge-graph domain, the description is too sparse. It doesn't explain offset/limit pagination, relation types, or the return format, even though an output schema exists.

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 each parameter is documented. The description adds no additional semantic value beyond the schema.

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

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

The description states 'All edges touching a term in a language', which gives a general idea of retrieving relationships but is vague about what 'edges' are and doesn't differentiate from similar sibling tools like 'polymarket_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?

There is no guidance on when to use this tool versus alternatives. No context for usage or exclusions are provided.

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

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

Annotations are all false and provide no safety hints, so the description carries the burden. It discloses rate limiting ('5 per identifier per day'), that it's free and doesn't count against quota, and that the team reads digests daily. This adds meaningful behavioral context beyond the 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 average but every sentence earns its place: purpose, usage triggers, scope exclusions, message formatting advice, and operational constraints are all distinct. It is front-loaded with the core purpose 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?

For a feedback tool with a nested context object, enum type, and no output schema, the description covers when to use it, what to include, what not to include, and rate limits. It fully equips the agent to invoke the tool correctly.

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

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

The schema already describes all parameters well (100% coverage), so the baseline is 3. The description adds valuable guidance for the message parameter: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' This goes beyond the schema's plain-text description and clarifies expected content.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly differentiates this feedback tool from sibling data/query tools by focusing on reporting issues rather than retrieving information.

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

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

Explicitly states when to use it: for bugs, feature/data_gap, or praise. Also provides exclusions ('ONLY for tools served by this Pipeworx connection') and directs users to other servers for non-Pipeworx tools, plus guidance for uncertainty ('Not sure? Pipeworx tool names are the ones this connection lists').

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 beyond annotations: data source (CF analytics-engine), privacy (no PII), returned fields (pack, tool, count), and caching (5min-1h). 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?

Concise, front-loaded purpose, use cases in bullet-like format, and additional details in the last sentence. No unnecessary words.

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

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

Given low complexity (1 param, no output schema, rich annotations), the description covers all needed info: what is returned, how it works, caching, and usage context.

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

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

Single parameter `window` with enum is well-described, including behavior implications (hot vs steady-state). Schema coverage 100% supports baseline 3, but description adds 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?

Clearly states the tool returns trending tools/packs and call volume over configurable windows, distinguishing it from siblings like ask_pipeworx or discover_tools.

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

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

Provides three explicit use cases (discovering hot data sources, confirming canonical tools, aligning use cases) and guidance on window selection for different needs.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) indicate safe, read-only, open-world behavior. The description adds critical behavioral details: the 'FILL CHECK' explains that realizable_edge_pp ≤ 0 means the arbitrage is not tradeable, and it references polymarket_fill_risk for custom sizing. 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 comprehensive but slightly verbose. It is well-structured with clear sections (modes, semantic anchor, partition filter, response details, fill check). Every sentence adds value, though some details could be trimmed without losing clarity.

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 thoroughly explains the response structure (opportunities array with fields, partition_check object, fill check details). It also addresses edge cases (low similarity, placeholder filter) and references a sibling tool for custom sizing, making it complete for agent 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?

Input schema has 100% coverage with descriptions for both parameters (event, topic). The description enriches these by explaining that event takes a slug (with examples) and topic takes a seed question, and it details how these modes affect the analysis (walking child markets, cross-event scanning, similarity checks).

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from sibling tools like polymarket_edges by focusing on arbitrage detection through specific mathematical checks, and it details three distinct usage modes (no args, event, topic) with specific behaviors.

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

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

Provides explicit guidance: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' Recommends event mode for specific markets and explains when cross-event mode is beneficial. No explicit when-not-to-use, but the clarity of modes makes it highly usable.

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 explains the three model families, caching (1h at KV level), response structure (by_segment, fed_candidates, _diagnostics), edge and Kelly calculation, and tradeable-edge knobs. It adds significant behavioral context beyond the annotations, which already indicate readOnlyHint, idempotentHint, etc. No contradiction.

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

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

The description is long but well-structured, front-loaded with the core purpose, and each section (segments, response fields, knobs, diagnostics) adds necessary detail. While it could be more concise, the complexity of the tool 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?

Given the tool's complexity (9 parameters, no output schema, nested structures), the description is highly complete. It explains the output structure, why segments may be empty, Fed bet handling, and how parameters affect results. This provides excellent context for the agent.

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

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

The schema already provides 100% coverage with detailed parameter descriptions. The tool description adds some context (e.g., summarizing knobs and explaining min_partition_leg_kelly), but it doesn't significantly enhance understanding beyond what the schema already offers. Baseline of 3 is appropriate.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and it's built for 'what should I bet on today'. It distinguishes itself from siblings by focusing on three specific model families and the Pipeworx data disagreement.

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 guidance on when to use the tool (for discovering opportunities without paging hundreds of markets) and mentions the tradeable-edge knobs. However, it does not explicitly compare with sibling tools like polymarket_arbitrage or polymarket_edge_tracker, leaving the agent to infer distinctions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds substantial behavioral context: it returns full edge_pp_net time-series, first_seen, trend, decay_pp_per_day, expired opportunities with lifespan_days, and snapshot_dates. It also discloses limits (60-day TTL, no intraday data) and data source (daily closes).

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 every sentence adds value. It front-loads the core question and then organizes response fields (tracked[], expired[], snapshot_dates[]) clearly. Could be slightly more structured with bullet points, but overall effective.

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 response structure including all fields and edge cases (gaps due to cache-miss, TTL bounding, start time). It covers the tool's complexity with 2 parameters and no nested objects completely.

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

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

Schema coverage is 100%, so both 'days' and 'window' are documented. The description adds meaning beyond schema: 'days' is lookback (default 14, max 30, with clamp 2-30), 'window' default is '1wk'. It also explains that history depth is bounded by 60-day TTL, adding subtle parameter constraint context.

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

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

The description states a specific verb+resource: 'Edge persistence and decay telemetry' and answers a concrete question: 'how long has this edge existed and is it shrinking?'. It distinguishes from sibling tools like polymarket_edges by focusing on time-series trend analysis rather than raw snapshot data.

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

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

The description provides clear context on when to use the tool ('Answers...'), including a concrete example differentiating fresh vs old wide edges. It explains interpreting results (trend, decay, lifespan) but does not explicitly name alternative tools for different use cases.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context beyond annotations: walking the order-book ladder, returning detailed metrics like slippage, fill details, and risks like partial basket fills converting arb into directional positions. 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 and well-structured with bold mode headers, but slightly verbose at several sentences. However, every sentence earns its place, and the information is front-loaded with the core 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?

Despite no output schema, the description comprehensively enumerates all return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, theoretical_sum, capture_ratio, profit_usd, per-leg details, thin_legs, forced_directional_risk) and explains their meaning. No gaps for an agent to use the tool correctly.

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

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

Schema coverage is 100%, but the description adds significant value: e.g., for size_usd it distinguishes buys vs sells and basket mode interpretation; for side it explains default auto behavior. This enhances 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 as a 'realizable-vs-theoretical edge check against live CLOB order-book depth,' with explicit modes (single-market and basket) and specific differentiation from sibling tools like polymarket_arbitrage and polymarket_edges by being a prerequisite validation step.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale (theoretical overround not capturable on thin books, partial fills causing unhedged positions) and implies when not to use (small trades).

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

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

The description goes far beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) by detailing responses (leg-by-leg prices, spread array), safety fields (compatibility_warning with three cases, temporal_alignment, skipped_cross_type/subtype counters), and behavioral traits like when the delta is meaningful and when to avoid trades. 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 dense but efficiently structured: it starts with the core purpose, then explains the two modes, response format, and safety fields in a logical order. Every sentence provides essential information without redundancy. The use of bold for modes and safety fields aids readability.

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

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

Given the absence of an output schema, the description thoroughly explains all output fields (leg prices, spread, top_spreads_pp) and crucial safety fields (compatibility_warning, temporal_alignment, skipped counters). It covers edge cases like mismatched bet shapes and temporal gaps, ensuring the agent understands when the output is actionable.

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

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

The input schema has 100% coverage with descriptions for all three parameters. The description adds value by explaining the relationship between topic and explicit tickers, providing examples ('fed', 'btc'), and clarifying that using both explicit tickers overrides the topic mapping. This enhances understanding beyond the schema alone.

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

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

The description clearly identifies the tool as a cross-venue spread analyzer between Kalshi and Polymarket for the same resolving question. It specifies the verb 'cross-venue spread' and the resource, distinguishing it from siblings like 'polymarket_arbitrage' by focusing on two venues. The explanation of market participant pools and delta signal further clarifies its unique 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 explicitly outlines two modes: topic shortcuts (pre-mapped macros) and explicit tickers for custom pairings. It provides clear guidance on when to use each, including a warning that most pre-mapped topics return compatibility warnings today. This helps agents decide between the tool and alternatives like 'polymarket_arbitrage' or other data tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description confirms it's an edge search but adds minimal behavioral context about combining parameters or response structure. Since annotations are rich, the description is adequate but not enhanced.

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 sentence that is concise and front-loaded with the core purpose. Every part contributes meaning 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 rich annotations and presence of an output schema, the description is adequate but lacks explanation of parameter combination behavior and default scoping (e.g., how offset/limit apply). An agent may benefit from more context on usage patterns.

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 71%, and the description lists parameters (rel, start, end, node, source) but does not explain how they combine (e.g., AND/OR logic) or provide additional semantics beyond the schema. Examples in the input schema partially compensate, but the description itself adds limited 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 'Generic /query edge search (combine rel, start, end, node, source)' clearly indicates the tool performs edge searches in a graph, specifying the main parameters. However, it does not explicitly differentiate itself from sibling tools like 'lookup' or 'deep_research', which may serve similar purposes.

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?

No guidance is provided on when to use this tool versus alternatives. With siblings such as 'lookup', 'search_within', and 'entity_profile', explicit context on when this low-level 'query' is appropriate would aid 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?

Adds scoping detail (by identifier) beyond annotations; 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?

Four sentences, no fluff, well-organized with clear functionality, usage, scoping, and pairing.

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?

Covers essential aspects for a simple retrieval tool; lacks return format details but not critical given examples.

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 description echoes schema info; minimal added value beyond 'omit to list'.

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

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

Clearly states it retrieves a value saved via remember or lists all keys, and differentiates 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 says when to use (look up stored context) and when not (save/delete via remember/forget), with concrete examples.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds critical behavioral details: mark_read flag affects future calls by marking events read, polling works fine, and the feed is also available via GET. 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 focused paragraph of 5 sentences, each adding value: purpose, return fields, filtering, mark_read behavior, alternative endpoint. It is front-loaded with the main purpose and avoids 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 exhaustive schema coverage and comprehensive annotations, the description fully covers return format, filtering, mark_read behavior, and provides an alternative access method. No output schema exists, but the return fields are described. The tool is well-understood for invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances semantics by providing examples (type filter 'sec_8k', since as ISO timestamp), explaining mark_read behavior, and noting limit defaults. This adds meaningful guidance 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 pulls fired events from a subscription feed, specifies return fields (source, citation_uri, payload), and distinguishes itself by mentioning an alternative endpoint for scripts/dashboards. The verb 'pull' and resource 'fired events' are 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 context for when to use this tool (polling works fine) and mentions an alternative GET endpoint for scripts/dashboards, implying when not to use this tool. However, it does not explicitly exclude usage scenarios or compare with sibling tools, leaving some room for ambiguity.

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 richly details behavioral traits beyond the annotations: it fans out to multiple sources, has fallback mechanisms, accepts various date formats, and returns structured data with citation URIs. No contradictions with annotations (readOnly, idempotent). The soft-fail for patents is explicitly noted.

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 query examples and provides thorough context. While every sentence adds value, it is somewhat long. However, the structure is logical, moving from examples to behavior to alternatives.

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

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

Given the tool's complexity (multiple sources, date windows) and the lack of an output schema, the description sufficiently explains what the tool returns (changes grouped by source, total_changes, citations). It also mentions the alternative tool for static profiles, making it complete for selection and invocation.

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

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

Schema coverage is 100%, but the description adds significant value: it explains the 'since' parameter accepts ISO dates or relative shorthand and recommends '30d' or '1m'. It clarifies 'value' accepts ticker or CIK, and 'type' is only 'company'. This goes beyond the schema's 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 begins with concrete example queries and explicitly states it is a change feed for a company. It distinguishes itself from the sibling 'entity_profile' tool, which is for static profiles. The verb 'fan out' and listing of sources (SEC EDGAR, GDELT, USPTO) makes the action and resource very clear.

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

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

The description provides explicit guidance on when to use this tool versus 'entity_profile' (static profile). It also explains internal fallback logic (GDELT preferred, GNews when rate-limited) and soft-fail behavior for USPTO. This gives clear context for expected behavior.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds the output range (0..1) and clarifies it's a semantic-relatedness score, which is not in annotations. No contradictions. However, it does not detail the model or knowledge base used.

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 sentence, no wasted words. The key details (what it does, output range) are front-loaded. Highly 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?

Output schema exists, so return value details are not needed. The description covers the core functionality. It could mention the underlying data source or default language handling, but the schema examples and parameter descriptions provide sufficient context. Missing use case guidance slightly lowers completeness.

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 coverage is 100% with descriptions for each parameter. The description does not add new meaning beyond the schema (e.g., 'node1' and 'node2' are already described). 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?

Clear and specific: 'Semantic-relatedness score (0..1) between two terms.' The verb 'compute' is implied, and 'score (0..1)' defines the output. It distinguishes from sibling tools like compare_entities or entity_profile by focusing on a numeric relatedness score.

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?

No guidance on when to use this tool vs alternatives. Lacks mention of use cases or when not to use. Sibling tools include other semantic/lookup tools, but the description does not differentiate.

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

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

Adds significant context beyond annotations: scoping by identifier, persistence differences (authenticated vs anonymous), 24-hour retention for anonymous, and cross-session use. No contradiction with annotations.

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

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

Two compact sentences front-loaded with purpose and usage, followed by essential behavioral details. No extraneous words.

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

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

Fully covers purpose, usage, behavior, parameter hints, and tool relationships. Given two simple parameters, no output schema, and rich annotations, no gaps remain.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds naming conventions (e.g., 'subject_property') and usage context, providing slight additional value 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?

Clearly states 'Save data the agent will need to reuse later' with specific examples (resolved ticker, target address, user preference) and distinguishes from siblings recall 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 instructs when to use ('when you discover something worth carrying forward') and pairs with recall/forget, providing clear usage context and alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral context: it notes that each call cascades through several lookup endpoints internally, and mentions auto-disambiguation for company inputs. This goes beyond the 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 well-structured, front-loaded with example queries, and every sentence serves a purpose. It covers examples, purpose, types, return details, and behavioral notes without redundancy. 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?

Given the tool has 2 required params, no output schema, and moderate complexity, the description fully covers what the tool does, its input types, return values, and even citation URIs. Combined with strong annotations and schema, the description is complete for an AI agent to select and invoke it correctly.

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

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

The input schema already covers 100% of parameter semantics, including enums and descriptions of 'type' and 'value'. The description reinforces these with examples (e.g., 'AAPL', '0000320193', 'ozempic') and what each type returns, but adds marginal new information beyond the schema's high coverage.

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

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

The description clearly states the tool's function: resolving user-spoken names into canonical/official identifiers required by other tools. It provides concrete examples ('ticker for…', 'CIK for…') and lists supported entity types, effectively differentiating it from sibling tools like 'lookup' or 'entity_profile'.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also mentions that it replaces 2-3 manual lookups, implying it's the go-to when an ID is needed. However, it does not name alternative tools or explicitly state when not to use it, so it falls short of a 5.

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

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

The description adds behavioral detail beyond annotations: 'Probes each entity ... with ai_visibility_check, ranks by score, surfaces which is most/least recognized' and specifies return fields (score, confidence, signal density). Annotations already indicate safety (readOnly, idempotent), so bar is lower; description enhances 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 concise (~3 sentences), front-loaded with purpose, and uses clear language. No unnecessary words or repetition, though it could include a bit more structure for readability.

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

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

The description covers main functionality but lacks details on error handling, edge cases (e.g., entity not found), or interpretation of returned scores. Given no output schema, additional context on return format would improve completeness.

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: 'First entry treated as subject for narrative' and 'Omit for just workers-ai' for models. This provides practical guidance beyond parameter descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes with ai_visibility_check, ranks by score, and returns a ranked list. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description provides explicit usage context: 'Useful for competitive AI-marketing audits' with an example question. It implies when to use against alternatives (e.g., instead of ai_visibility_check for single entity) but does not explicitly mention 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds beyond this: explains the composite nature (fans out across deps.dev and bundlephobia), mentions partial failures and timing (bundlephobia first measurement 5-30s), and sources_failed list. No contradictions.

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

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

The description is a single paragraph but dense with information. It front-loads the composite nature. While it could be broken into bullet points, it remains clear 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?

No output schema exists, but the description explains the return structure (summary block, per-advisory detail, links, alternative versions) and covers edge cases like partial failures. It is fairly complete.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds additional context: explains the default version behavior and that scoped packages are accepted, adding value beyond the schema.

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

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

The description clearly states the tool's purpose as a composite check for npm packages covering license, advisories, and bundle size. It distinguishes itself from siblings by specifying the ecosystem (NPM) and mentioning alternative tools like deps.dev:version.

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 an agent asks "is X safe / popular / small"...' It also notes limitations: NPM only in v1, and mentions partial failures. This provides clear when-to-use guidance.

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

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

Annotations declare readOnlyHint, idempotentHint, non-destructive. Description adds significant behavioral details: truncation cap (200K chars), embedding model (BGE-base-en), window size (500-char overlapping), offset feature. No contradiction with annotations.

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

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

Three concise sentences, front-loaded with purpose. Every sentence earns its place: function, use-case, technical details. Zero 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?

No output schema, but description fully covers return format (passages with offsets and similarity scores). Also covers limits, model, truncation, and pairing with sibling. Complete for a tool with 3 simple params.

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

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

Schema covers all 3 params with descriptions. Description adds meaning: explains query parameter with example queries ('supply-chain risk', 'fiscal year 2024 revenue'), clarifies the truncation behavior for text parameter, and mentions output features (offsets, scores) not otherwise documented.

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, specifies inputs (text + query) and output (top-N passages with offsets and similarity scores). It distinguishes from siblings by explicitly pairing with ask_pipeworx_grounded and contrasting with fetching full records.

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 highlights context-saving benefit. Also provides an alternative workflow with ask_pipeworx_grounded, giving clear when-to-use guidance.

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

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

Annotations already provide readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds significant behavioral context: returns subscription id, OAuth requirement, supported event types with examples, delivery channel options with specific constraints (SMS phone verification, 10/day cap, webhook HMAC signing, auto-disable after 10 failures). Exceeds annotation coverage.

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

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

The description is well-structured: starts with action, then requirement, supported types, delivery channels. Every sentence adds value. Slightly lengthy but appropriate given the detail needed for complex subscription types. Could be slightly more concise, but no waste.

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

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

Given the tool's complexity (3 parameters with nested objects, no output schema), the description is complete. It explains return value (subscription id), all type-specific parameters, delivery options with restrictions, and prerequisites. No apparent gaps that would hinder an agent's correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds substantial meaning: explains enum values with real-world examples (e.g., sec_8k items field), details type-specific params structure, and elaborates on delivery sub-fields including security (webhook HMAC) and rate limits (SMS cap). This provides clarity beyond the schema.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' This is a specific verb+resource combination. The tool is meaningfully distinguished from siblings like list_subscriptions, unsubscribe, and recent_alerts, which serve different functions.

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 a prerequisite (Pipeworx OAuth account required, anonymous/BYO cannot persist), which guides when to use. It mentions the always-on feed available via recent_alerts as an alternative for pulling alerts without subscribing. However, it could more explicitly contrast with other tools or state when not to use subscribe.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns example questions with exact tool and argument shapes, drawn from a live catalog, and differentiates behavior with/without the topic argument. 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 synonyms and purpose, then explains output and usage. It's a bit long but every sentence adds value. Could be slightly more concise but still 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 the tool's simplicity (one optional parameter, no output schema), the description thoroughly explains what it returns (category-bucketed example questions with tool+argument shapes) and how to call it. No gaps for the intended use case.

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

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

Schema coverage is 100% (one parameter fully described). The description adds meaning by explaining the effect of omitting vs. providing 'topic' (full spread vs focused), and lists example values beyond the schema's enum list.

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

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

The description clearly states the tool is an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It distinguishes itself from siblings by indicating it should be used first when the agent doesn't know what Pipeworx can do.

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

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

Explicitly recommends using this tool first when unfamiliar with Pipeworx, and offers to focus on a topic by passing a parameter. It also implies when not to use it (if already know what to ask).

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

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

Discloses that the row is deactivated (not deleted) and that historical events remain available, which goes beyond the annotations (destructiveHint=false). 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, each adding value. First sentence states action and constraint, second explains behavioral effect. No wasted words.

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

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

Complete for a simple mutation: covers purpose, usage constraint, and behavioral effect. No output schema needed.

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

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

Schema covers 100% of parameters with description for 'id'. Description adds no extra meaning beyond the schema, so baseline score applies.

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

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

Clearly states the action (cancel) and resource (subscription). 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?

Mentions ownership enforcement and that only own subscriptions can be canceled, providing clear context. However, no explicit comparison to 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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds significant context: it explains the two processing paths (structured SEC EDGAR for financial claims, grounded pipeline for others), the return format (verdict, value with citation, reasoning), and that it replaces multiple calls. 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 a single paragraph that efficiently front-loads the purpose with example phrasings. Every sentence adds value, covering purpose, usage, routing, return values, and efficiency. No redundant 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?

Despite no output schema, the description fully explains return values: verdict (confirmed, approximately_correct, refuted, inconclusive, unsupported), actual value with pipeworx:// citation, and reasoning. It also covers the two processing paths and the role of tolerance_pct. The description is complete for the tool's complexity.

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

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

Schema description coverage is 100% with both parameters described. The description adds context on tolerance_pct usage (overrides implied tolerance, set 1-2 for hallucination detection) and clarifies the scope of the claim parameter (company financial vs other). This goes beyond the schema descriptions.

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

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

The description clearly states the tool's function as natural-language claim verification against authoritative sources, lists example phrasings, and distinguishes between company financial claims and other claims. It also notes that it replaces multiple sequential calls, differentiating 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 explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides context on routing (structured vs grounded). However, it does not mention when not to use this tool or compare it to potentially overlapping sibling tools like ask_pipeworx_grounded or deep_research.

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