Ygoprodeck

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, nondestructive. Description adds significant behavioral details: default free model, BYO key for Anthropic, cost implications, return structure (score, confidence, signals, raw_response). 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?

Description is two sentences front-loaded with core function, then details on models and return format. Every sentence adds value, no redundancy, no fluff. Perfectly sized for quick comprehension.

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

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

Tool has 4 parameters (all documented), no output schema, but description summarizes return format per model and combined. Annotations cover safety/read-only. For a probing/scoring tool, this description is complete enough to use without confusion.

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

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

Schema description coverage is 100%, but the description adds extra context: entity examples, supported model values with default, _apiKey usage clarified as optional and passed through, context for disambiguation. This goes beyond schema to guide parameter usage effectively.

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

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

Description clearly states the tool probes LLMs for brand visibility and scores it 0-100 per model. It distinguishes from sibling tools like ask_pipeworx (general Q&A) and deep_research (broader research) by specifying 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Verb+resource+scope is explicit.

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

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

Description provides clear use cases (AI-marketing audits, brand checks, monitoring) and explains default vs paid models. It doesn't explicitly state when not to use or list alternative tools, but the context signals and sibling list give implicit guidance. Missing explicit exclusions prevents a 5.

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

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

Annotations already declare safe read-only, open-world, idempotent, non-destructive behavior. The description adds valuable context: routing across many tools, argument filling, stable pipeworx:// citation URIs, works on every tier, and 'one fast call'. No contradiction with annotations, but the exact response format is not fully detailed.

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 section adds value: preference over web search, routing behavior, usage cues, examples, and escalation paths. Front-loaded with the most important directive ('PREFER OVER WEB SEARCH'). Strictly not concise, but justified for a central, 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?

Despite having no output schema, the description explains the output shape ('structured answer with stable pipeworx:// citation URIs'), covers major use cases, alternatives, and provides actionable examples. It doesn't detail response JSON structure or error behavior, but for an AI agent the provided context is largely sufficient.

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

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

Schema coverage is 100% with 'question' and five aliases fully documented. The description adds examples of natural-language queries but does not explain parameter semantics beyond what the schema provides. Baseline of 3 is appropriate since the schema carries the burden.

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

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

The description clearly states the tool answers factual questions by routing them to 5,462 tools across verified sources and returning structured answers with citations. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, and from web search, making its unique role unmistakable.

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

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

The description gives explicit usage directives: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', 'START HERE for most questions', and 'Step up only when needed' with named alternatives and examples. This is exemplary guidance, covering when to use it and when not to.

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

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

The annotations already mark it as read-only, idempotent, open-world, and non-destructive, and the description adds meaningful behavioral context beyond that: it is an experimental edge with live candidate routing, no active candidate currently, and no fallback because it is a full working router. It also discloses that behavior may change when candidates are under test, which is valuable for an agent deciding whether to use it.

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 identity and equivalence, and every sentence contributes useful context about experimental status, usage, and fallback behavior. It is slightly verbose with the historical date and the emphasis on 'falls back to nothing,' but overall it is appropriately sized for a tool with this complexity.

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

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

For a complex universal router with no output schema, the description compensates by stating the same response shape as ask_pipeworx, current experimental status, and exact equivalence when no candidate is active. It does not enumerate response fields, but the reference to the stable sibling and the rich annotations give an agent enough context to invoke and interpret results correctly.

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

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

The input schema has 100% coverage, describing 'question' and all five aliases with clear descriptions, so the baseline of 3 applies. The description only references 'same arguments' generically and does not add parameter-level meaning beyond what the schema already provides.

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

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

The description clearly identifies ask_pipeworx_beta as a beta version of the ask_pipeworx universal router, specifying that it provides the same 5,462 tools, arguments, and response shape. It also differentiates it from the stable sibling by mentioning candidate routing improvements, making the tool's purpose and scope 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 states when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that results are compared against the stable router to decide what merges, implicitly naming ask_pipeworx as the stable alternative. This gives clear context and an explicit alternative.

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

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

Goes well beyond the annotations by disclosing the exact return structure (answer, evidence, confidence, source, fetched_at, refusal_reason), detailed refusal reason enum, and the cost of one extra LLM call. It also clarifies the grounding mechanism (extracts only from tool result). No contradiction with annotations; readOnlyHint and openWorldHint are consistent with the read-only, open-world behavior described.

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

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

The description is front-loaded with the core purpose in the first sentence and packs in important details about return shape, refusal reasons, usage, and cost. It's slightly verbose with the full refusal enum, but every sentence adds value, so it remains 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 no output schema, the description compensates by fully specifying the return contract and refusal behavior. It also explains when to use the tool, what makes it different from the sibling, and the cost implication. Even with the added complexity of 1,419 sources and 5,462 tools, the description gives enough to select and call it confidently.

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

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

Schema coverage is 100% as all six parameters are well-documented aliases for question. The description adds no additional parameter-level detail, but the schema fully handles it. With high coverage, baseline 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 identifies the tool as a hallucination-resistant answer mode for high-stakes reads, with a specific verb ('ask') and resource (Pipeworx grounded extraction). It distinguishes from sibling ask_pipeworx by explaining the extraction-only behavior, making its unique purpose explicit.

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: whenever an answer will be quoted, cited, or acted on, and lists example domains. Also provides a clear alternative: 'prefer ask_pipeworx for casual lookups' and explains the trade-off (extra LLM call). This is exemplary 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, openWorldHint, idempotentHint, destructiveHint=false. The description massively enriches this with details on fan-out patterns, response shapes, resolver contract, parent event extraction, news fields, safety checks, wide spread handling, and resolution rules. No contradiction with annotations.

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

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

The description is very lengthy and detailed. While it front-loads the purpose, it includes extensive enumeration of fan-out examples and edge cases. Could be more concise by separating core functionality from detailed examples, but structure is logical with sections.

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 input types, fan-out to many data sources, various response shapes, edge cases), the description is exceptionally complete. It covers resolution confidence, parent events, news fields, safety, liquidity, and cancellation rules. No output schema exists, but the description adequately documents return shape.

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%. The description adds significant meaning: explains market input types (slug, URL, text), depth (quick vs thorough), and include_raw (default false, when to use). This goes beyond the schema's property descriptions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and includes usage examples. It distinguishes from sibling tools like polymarket_edges by being a comprehensive research call.

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

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

Explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides clear context and examples. Lacks explicit when-not-to-use guidance, but the purpose is well-defined.

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 as true, and destructiveHint false. The description adds valuable behavioral context: it explains that for companies, it pulls the LATEST 10-K data from SEC EDGAR/XBRL with correct handling of off-calendar fiscal years, and for drugs, it pulls specific counts. It also mentions the result format (paired data + citation URIs) and efficiency (replaces 8–15 sequential lookups). No contradiction with annotations.

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

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

The description is concise, front-loading key trigger phrases like 'Compare X and Y' and 'ALWAYS PREFER'. Every sentence adds value, covering purpose, usage guidance, data sources, sorting, and output format. No redundant or extraneous 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 lacking an output schema, the description explains the return format (paired data + citation URIs) and sorting behavior. It also addresses edge cases (off-calendar fiscal years) and specifies data sources (SEC EDGAR/XBRL, FAERS). This is comprehensive for a comparison tool, leaving little ambiguity for an AI agent.

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

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

Schema coverage is 100% with both parameters described. The description enriches the schema by explaining what data is fetched for each 'type' (company vs. drug) and provides example values (tickers/CIKs for company, drug names). It also notes the maxItems constraint (5) and minItems (2). This adds meaningful context beyond the schema's basic 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 performs side-by-side comparison of 2–5 companies or drugs, with example queries like 'Compare X and Y'. It specifies the exact metrics pulled for each type (revenue, net income, etc. for companies; adverse-event counts, approval counts, trial counts for drugs), making the purpose unambiguous and distinct from sibling tools like '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 explicitly advises to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. It also explains that results are sorted by primary metric. However, it does not mention when NOT to use it (e.g., if more than 5 entities are needed or other data types), leaving a gap in exclusion criteria.

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

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

Goes far beyond annotations by disclosing that it 'never invented' answers, returns 'gaps[]' for unanswered facets, 'contradictions[]' for disagreeing findings, uses 'semantically excerpted' passages, and only includes 'citation_uri' when it can actually be served by resources/read. Also discloses timing expectations (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 but dense and front-loaded with critical information (account requirement, alternatives). Every sentence adds value, though it could be more concise without losing essential details. The structure uses semicolons and clauses effectively to pack a lot of context.

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

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

With no output schema, the description fully explains the return format: 'findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding, with explicit gaps[]'. It also covers contradictions, hop field, citation resolvability, and timing. This is highly complete for a complex research tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaningful context beyond the schema: depth 'quick=3 (single hop)', 'standard=5 (default; adds a gap-recovery hop...)', 'thorough=8 (paid; adds a full iterative hop...)'. It also clarifies that question can be 'broad/multi-part', enhancing the schema's description.

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

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

The description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources... decomposes your question into focused facets, routes each to the right one of 5,462 tools IN PARALLEL, and returns a findings packet.' It also explicitly distinguishes from siblings by noting 'this is NOT open-web search' and 'For a single lookup use ask_pipeworx.'

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data,' 'For a single lookup use ask_pipeworx (one LLM call, not many),' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' Also mentions the account requirement and fallback if not signed in.

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. Description adds that results include full input schemas with curated examples and are ready to call directly, providing useful behavioral context beyond annotations. No contradiction.

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

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

Description is moderately long but well-structured, front-loading the main purpose and use cases. Every sentence adds value, though a slight trimming could improve conciseness.

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 and no output schema, the description adequately explains what is returned (top-N tools with names, descriptions, schemas). Provides enough context for effective use.

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

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

Schema coverage is 100%, so baseline 3. Description mentions accepting natural language description and aliases, which is already in schema. Does not add significant new meaning beyond schema details.

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

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

The description clearly states the tool finds tools by describing data or task, listing many example domains (SEC filings, FDA drugs, etc.). It differentiates from siblings by emphasizing it's for discovering available tools, not querying data, and explicitly says 'Call this FIRST' to see the option set.

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

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

Provides explicit when-to-use: 'when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available'. Lacks explicit when-not or exclusion cases, but context implies not for direct data retrieval.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds info about data sources, parallel execution, soft-fail for patents, and return fields, which enhances transparency without contradicting annotations.

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

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

The description is fairly long but each sentence adds value. It is front-loaded with example queries and a clear purpose. While not overly concise, it is well-structured and information-dense.

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

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

Despite lacking an output schema, the description thoroughly lists expected return fields (cik, company_name, filings, fundamentals, patents, news, LEI). Combined with annotations and simple input schema, this provides sufficient completeness 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?

Schema already covers parameter descriptions (100% coverage). Description reinforces that 'type' must be 'company' and 'value' can be ticker or CIK, and adds the crucial constraint that names are unsupported, directing to resolve_entity. This adds meaningful guidance beyond schema.

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

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

The description specifies 'full cross-source profile of a US public company in ONE parallel call' and lists data sources and outputs. It distinguishes itself from single-pack lookups and directs to resolve_entity for names, making the purpose clear and differentiating from siblings.

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

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

Explicitly states when to use ('Tell me about X' queries) and when not to use (names not supported, use resolve_entity first). Recommends ALWAYS PREFER over chaining individual lookups for holistic views, providing clear guidance.

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

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

The description matches the destructiveHint annotation and adds context about clearing sensitive data. While annotations already indicate destructiveness, the description provides useful behavioral context 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 very concise with two sentences: the first clearly states the action and resource, the second gives usage guidance. 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?

For a simple tool with one parameter and no output schema, the description covers purpose, usage guidelines, and context sufficiently. The annotations and schema provide the remaining details.

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

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

The schema has 100% coverage with a description for the 'key' parameter. The description does not add additional meaning beyond what the schema already provides, so it meets the baseline for schema coverage.

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

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

The description clearly states the verb 'Delete' and the resource 'a previously stored memory by key', and it distinguishes this tool from sibling tools like 'remember' and 'recall' which perform different operations.

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

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

The description provides explicit guidance on when to use the tool (stale context, task done, clear sensitive data) and mentions pairing with other tools. However, it does not explicitly state when not to use it.

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

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

Annotations already cover safety and idempotency. The description adds value by detailing the extraction process (title, description, key links) and output format (single text blob). 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 concise at three sentences, front-loaded with the main purpose, and efficiently covers process and use cases without waste.

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

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

The description provides sufficient context for the tool's output and process. It covers parameters and use cases adequately. No output schema exists, but the description explains the output format. Slightly lacking on error handling or edge cases.

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

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

Both parameters are fully described in the input schema with 100% coverage. The description does not add new information about parameters beyond what the schema provides.

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 an llms.txt file for a URL, specifying the output format and use cases. It distinguishes from sibling tools by focusing on the specific standard file generation.

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

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

The description lists specific use cases (client indexing, own project, competitor audit) but does not explicitly state when not to use the tool or suggest alternatives. However, given the narrow purpose, the guidance is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, indicating a safe read operation. The description adds value by detailing the specific information returned (type, description, ATK/DEF, level, etc.), which goes beyond the annotations. No contradictions. However, it does not mention error handling for non-existent card names.

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

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

The description is a single, well-structured sentence that efficiently conveys the tool's purpose and output. Every word serves a purpose, with no unnecessary information.

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

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

For a simple lookup tool with one parameter and no output schema, the description is sufficiently complete. It lists the types of data returned. A minor gap is lack of mention about behavior when a card is not found, but overall adequate given the tool's simplicity.

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

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

The schema has 100% description coverage with a clear description of the 'name' parameter and examples. The description repeats the 'exact name' requirement but does not add new semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states 'Look up a single Yu-Gi-Oh! trading card game (TCG) card by its exact name.' It specifies a specific verb ('Look up'), a clear resource ('single card'), and a unique constraint ('exact name'). This distinguishes it from siblings like 'search_cards' (likely fuzzy) and 'random_card'.

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 implies usage by requiring 'exact name', but does not explicitly state when to use this tool versus alternatives, nor does it mention when not to use it. Sibling names provide hints, but the description itself lacks explicit guidance on exclusions or prerequisites.

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. Description adds value by listing specific return fields (id, type, params, etc.), which are beyond annotations.

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

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

Two concise sentences, 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?

For a simple read tool with one optional parameter and no output schema, the description covers the purpose and return fields. No mention of pagination or limitations, but complexity is low.

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 one boolean parameter documented. Description does not add extra meaning beyond the schema, so baseline 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 action (list subscriptions) and specifies the caller's subscriptions, distinguishing from siblings like subscribe/unsubscribe. It also lists return fields, adding precision.

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: 'review what you're monitoring before adding more or to find an id to cancel,' providing clear context and excluding other uses.

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, but the description discloses useful behavioral traits: rate-limited to 5 per identifier per day, free, does not count against tool-call quota, and feedback is read in daily digests. It does not detail authentication or side effects, but for a feedback submission tool this is adequate 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 dense but every sentence earns its place: core action, use cases, scope exclusion, formatting guidance, and operational details (rate limits, quota). It is front-loaded with the primary purpose and avoids filler, making it efficient for an agent to parse.

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

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

Given only 3 parameters (one nested), no output schema, and a straightforward feedback action, the description fully covers what to submit, how to scope it, and what happens to the feedback (digests, roadmap impact). It leaves no critical gaps for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful guidance by mapping the type enum to realistic scenarios (e.g., bug = wrong/stale data) and instructing users to describe issues in terms of Pipeworx tools/packs rather than paste prompts, which goes beyond the schema's field-level descriptions.

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

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

The description opens with a clear action ('Tell the Pipeworx team'), specifies the resource (Pipeworx team), and defines the scope (something broken, missing, or needs to exist). It distinguishes itself from sibling research/memory tools by framing this as feedback submission rather than an analytical or retrieval operation.

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 enumerates trigger conditions for each feedback type (bug, feature/data_gap, praise) and provides a clear exclusion rule: only for tools served by this Pipeworx connection, with an alternative action (file with the other server) for non-Pipeworx tools. It also adds practical limits (rate-limited to 5/day) that inform when to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, destructiveHint. Description adds valuable behavioral context: source (CF analytics-engine), privacy (no PII), caching duration (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?

Description is concise (3 sentences), front-loaded with purpose, then use cases, then implementation details. Every sentence adds value. No superfluous content.

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

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

For a tool with 1 optional param and no output schema, the description fully covers what the tool does, its inputs, behavior, and use cases. Annotations provide safety guarantees. No gaps.

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

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

Schema has 100% coverage with enum and description. Description adds semantic nuance: 'shorter windows surface what's hot right now; longer windows show steady-state demand.' This enhances understanding beyond schema.

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

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

Description clearly states the tool returns top tools, top packs, and total call volume over a window. Uses specific verb 'returns' and specifies the resource ('what other AI agents are calling on Pipeworx'). Distinguishes from sibling tools like discover_tools by focusing on trending/popularity.

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?

Lists three explicit use cases (discovering hot data sources, confirming canonical choice, aligning use case). Implicitly distinguishes from search tools. Could improve by adding when not to use, but current guidelines are clear and helpful.

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 confirm read-only, idempotent, non-destructive behavior. The description adds substantial context: scans top ~200 markets, uses Jaccard similarity ≥0.30, filters placeholder slugs, computes partition check with gap from 1, and performs fill check against live CLOB depth. These details are beyond what annotations provide and accurately describe behavioral traits.

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

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

The description is lengthy but well-structured. It front-loads the core purpose and then details each mode. Every sentence adds value, though some details about fill check and semantic anchor could potentially be trimmed. However, for a complex analysis tool, this level of detail is justified.

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

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

Given the tool's complexity (two modes, multiple heuristics, no output schema), the description is remarkably complete. It explains the response structure (opportunities[], partition_check fields), fill check logic, custom sizing reference, and edge cases like placeholder filtering and Jaccard similarity. 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?

Both parameters (event, topic) are described in the schema with full coverage. The description adds significant meaning: explains event slug format, that topic triggers cross-event scanning, and the default behavior when no args. It also clarifies the difference between the two modes and what they accept (e.g., full URLs for event).

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between default trending_scan, event mode, and topic mode, using specific verbs like 'Find' and explaining the resource (Polymarket). It differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description provides explicit guidance on when to use each mode: call with no args for trending_scan, use event for a specific market, and topic for cross-event scanning. It explains the benefits of cross-event mode and recommends event mode for specific markets. It also warns against trading when fill check shows realizable edge ≤0 and suggests polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds rich behavioral details: three model families, response segments, caching (1h at KV level), tradeable-edge knobs, and diagnostics, going well beyond annotations.

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

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

The description is lengthy but well-structured with numbered segments and response details. It is front-loaded with the core purpose. While verbose, every sentence adds value 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?

Despite no output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, diagnostics) and model logic. Combined with complete parameter schema and annotations, it leaves no gaps.

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

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

Schema coverage is 100% with detailed descriptions. The description adds context on how knobs affect output (e.g., tradeable-edge filters, caching keyed on knobs), providing extra meaning 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 scans Polymarket markets to return opportunities where Pipeworx data disagrees with market price, using specific verbs and resources. It distinguishes from sibling tools by focusing on Pipeworx-driven edge discovery.

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 implies usage for finding betting opportunities but does not explicitly state when to use this tool over siblings like polymarket_arbitrage or polymarket_edge_tracker. No when-not-to-use guidance is 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 already indicate safe, read-only, idempotent behavior. The description adds extensive behavioral details: response structure (tracked, expired, snapshot_dates), decay computation, and limitations (60-day TTL, snapshot start). 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 well-structured with a purpose statement, args, response, and limits sections. It's slightly verbose but clear and front-loaded with key 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?

Given no output schema, the description thoroughly explains the response format and interpretation, covering all relevant aspects of the tool's output and limitations.

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

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

Schema covers both parameters with descriptions. The description adds defaults and bounds for 'days' (default 14, max 30) and clarifies the 'window' options, providing 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 it provides edge persistence and decay telemetry from daily snapshots, answering a specific trading question. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis rather than current edges.

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

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

The description explicitly explains when to use (to understand edge history and decay) and provides context (old wide edges are different from fresh ones). It doesn't list when not to use, but the purpose is clear enough to avoid misuse among siblings.

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

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

The description aligns with annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) and adds rich behavioral detail: walks the ladder, returns specific fields like verdict, thin_legs, and forced_directional_risk. It explains the risk of partial basket fills converting arb into unhedged directional positions, which is critical 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 comprehensive but somewhat verbose, with multiple detailed sentences. It effectively front-loads the main purpose and uses bold for emphasis. Some redundancy exists (e.g., listing return fields in paragraph form could be more concise), but overall it's well-structured.

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

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

Despite no output schema, the description thoroughly documents all return fields for both modes, including edge cases (thin_legs, forced_directional_risk) and usage constraints (size limits, required parameters). It provides complete context for safe and 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%, but the description adds significant meaning: explains how size_usd is interpreted differently in single-market vs. basket mode, clarifies default values, and describes the auto-detection logic for side in basket mode. This goes well beyond the schema descriptions.

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

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

The description clearly states it performs an edge check against live order book depth, distinguishing between single-market and basket modes with specific verbs (e.g., 'walks the ladder', 'returns'). It fully explains the tool's purpose and differentiates the two modes.

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 provides context for why it's needed (theoretical edge not capturable on thin books, partial fills cause unhedged positions). However, it does not explicitly name alternative tools for different scenarios.

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 extensive behavioral context: modes, response structure, safety fields (compatibility_warning with two cases), temporal_alignment, and counters for skipped comparisons. It discloses that spreads may be meaningless under certain conditions (temporal misalignment, incompatible bet shapes). No contradiction with annotations.

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

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

The description is long but well-structured: TWO MODES, RESPONSE, SAFETY FIELDS. Each sentence adds necessary detail. While it could be slightly shorter, the structure aids comprehension. No redundant or tautological statements.

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

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

Given no output schema, the description fully explains the return format (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, counters). It covers all key behavioral aspects: modes, safety fields, and when spreads are invalid. For a tool with 3 optional parameters and no output schema, it is complete.

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

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

Schema coverage is 100% (all 3 parameters described in schema). The description adds value by enumerating the 10 valid topic values, explaining that explicit tickers override the topic-mapped side, and giving examples. This goes beyond the schema's brief descriptions.

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

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

The description clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit tickers) and distinguishes from potential sibling tools by emphasizing cross-venue comparison. The verb 'spread' and resource 'cross-venue' are precise.

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

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

The description explicitly explains when to use each mode: topic shortcuts for 10 pre-mapped macro topics, explicit tickers for custom pairings. It warns that most pre-mapped topics return compatibility warnings, guiding against blind trust. It also explains safety fields that indicate when spreads are invalid, but does not explicitly contrast with sibling tools like polymarket_arbitrage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds value by specifying the returned details (type, ATK/DEF, prices, etc.), providing behavioral context beyond annotations.

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

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

The description is a single, front-loaded sentence that efficiently conveys purpose, resource, and output details. 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?

Given the tool's simplicity (no parameters, no output schema), the description adequately covers the return content. It could mention that it returns exactly one random card, but the current text is sufficient for an agent to understand the tool's behavior.

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

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

There are zero parameters, and schema coverage is 100% (trivially). The description adds meaning by describing what the tool returns, which is necessary since no output schema exists. Baseline 4 for zero parameters is appropriate.

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

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

The description clearly states the action 'Get' and the resource 'a random Yu-Gi-Oh! TCG card', listing specific details returned. It distinguishes from sibling tools like 'get_card' (specific card) and 'search_cards' (search by criteria).

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 implies usage when a random card is wanted but does not explicitly state when to use alternatives or provide exclusion criteria. Sibling tool names are provided in context but no guidance in text.

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. The description adds useful behavioral context: scoping to identifier and the ability to list all keys by omitting the 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 two sentences, front-loaded with purpose, and every sentence adds essential information without redundancy.

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

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

Given the tool's low complexity (1 optional parameter, no output schema), the description fully covers purpose, usage, behavior, and parameter semantics. No gaps.

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

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

With 100% schema coverage, the description still adds value by clarifying that omitting the key lists all saved keys, which is not explicit in the schema's description.

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

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

The description clearly states the tool retrieves a saved value or lists keys, distinguishes it from siblings 'remember' and 'forget', and specifies the resource ('value previously saved via remember').

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

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

The description explicitly says when to use: to look up stored context, and pairs with remember/forget for saving/deleting. It mentions scoping but does not explicitly state when not to use or alternative tools beyond siblings.

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

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

The description states that setting mark_read:true flags events as read, implying state modification, which contradicts the annotation readOnlyHint=true. This is a clear contradiction, making the description less reliable despite being more accurate than the annotation.

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

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

The description is front-loaded with the primary purpose, followed by details on content, filtering, mark_read, and polling. Each of the four sentences adds necessary information without fluff, making it concise and well-structured.

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

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

Given the tool's simplicity (5 optional parameters, no output schema), the description covers key aspects: output content, filtering, mark_read side effect, and alternative access. Missing details like pagination or error handling are not critical for this 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%, so the schema already documents all parameters. The description adds value by explaining mark_read behavior ('flag returned events read so the next call only shows newer ones') and providing context about the feed source, moving beyond 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 starts with 'Pull fired events from your subscription feed,' clearly specifying the verb (pull) and resource (events from subscription feed). It details what each event carries (source, citation_uri, raw payload), distinguishing it from sibling tools like list_subscriptions or subscribe.

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 usage guidance: 'Filter by type and/or since' and mentions 'Polls work fine; the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards,' offering an alternative access method. However, it does not explicitly compare with other tools or state when not to use this tool.

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

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

Annotations already indicate safe read operation (readOnlyHint, openWorldHint, etc.). Description adds valuable context: fan-out to multiple sources, fallback mechanism for news (GDELT preferred, GNews when rate-limited), soft-fail for USPTO, and return structure with changes grouped by source and citation URIs.

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

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

Single well-structured paragraph with example queries, functionality, parameter details, and sibling distinction. Every sentence adds value without redundancy.

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

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

Covers purpose, usage, parameters, return structure, and fallback behaviors. Adequate for a 3-parameter tool without an output schema, as description describes the output format.

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

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

Schema description coverage is 100%, but description adds beyond schema e.g., 'since accepts ISO date ("2026-04-01") or relative shorthand ("7d", "30d", "3m", "1y")' and 'value: Ticker (e.g., "AAPL") or zero-padded CIK (e.g., "0000320193").' Provides practical usage tips.

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 defines the tool as a change feed for a company, listing example queries and specifying sources (SEC EDGAR, GDELT→GNews, USPTO). It also distinguishes from sibling tool entity_profile, stating when to use each.

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 on when to use this tool vs. entity_profile ('Use entity_profile instead when you want the static profile...'). Also provides example use cases and parameter recommendations like 'Use "30d" or "1m" for typical monitoring.'

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

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

The description adds behavioral details beyond annotations: key-value pair scoped by identifier, persistence for authenticated users (persistent) vs anonymous (24 hours). Annotations already indicate idempotentHint=true and destructiveHint=false, so the description complements 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 a single dense paragraph covering purpose, usage, behavior, and pairing. It is well-structured but could be slightly more concise.

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

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

For a simple tool with two string parameters and no output schema, the description covers purpose, usage, persistence, and tool pairing. It is complete enough for an agent to understand and 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%, and the description provides example values for both 'key' and 'value', adding practical meaning beyond the schema's basic 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 explicitly states 'Save data the agent will need to reuse later' and provides concrete examples (resolved ticker, target address, user preference, research subject). It clearly distinguishes between sibling tools like '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?

The description advises to 'Use when you discover something worth carrying forward' and pairs with 'recall to retrieve later, forget to delete'. While it gives clear context, it does not explicitly state when not to use the tool.

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

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

Annotations already mark it read-only, idempotent, and non-destructive. The description adds substantial behavioral context: each call cascades through several lookup endpoints, returns specific fields (ticker, CIK, company_name, RxCUI, ingredient, brand), and includes citation URIs. This goes well beyond the annotations.

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

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

The description is well-structured with examples, a clear 'SUPPORTED TYPES' list, and explanation of the cascading behavior. It is somewhat lengthy but every part contributes contextual value; only minor trimming would make it fully concise.

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

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

Given no output schema and the need to describe two entity types with distinct identifiers and citations, the description is exceptionally thorough. It covers return fields, input variations, internal behavior, and the tool's role in the broader toolset. There is no missing essential context.

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

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

Schema coverage is 100% and the schema already explains input formats for both types. The description repeats those formats with examples and adds 'auto-disambiguated' for company, but this is marginal extra meaning. It does not compensate for any schema gap because there is none.

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 resolves a name to a canonical/official identifier, using specific verbs like 'resolve' and 'look up'. It distinguishes itself from siblings by emphasizing that other tools require these identifiers as input and by giving concrete examples ('What's the ticker for…' / 'find the CIK for…').

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear when-to-use guidance. However, it does not mention when not to use it or name alternatives, though the context of sibling tools implies it replaces manual lookups.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds value by explaining the internal behavior (probing each entity with ai_visibility_check, ranking) and the output structure (ranked list with score, confidence, signal density). No contradictions. Could have mentioned potential rate limits but not required given annotations.

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

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

Two sentences, front-loaded with the core purpose. Every sentence is informative with no repetition or fluff. The structure efficiently communicates the action, process, and typical use case.

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 return value details (ranked list with score, confidence, signal density) and mentions key parameters like models and context. However, it relies on the schema for the exact entity count range (2-8) and default model behavior. For a tool without an output schema, it is thorough but could be slightly more explicit about limits.

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 context beyond schema by stating that the first entity is treated as the 'subject' for narrative and the rest as competitors, which is not in the schema. It also re-emphasizes the use of _apiKey 'per probe'. This adds modest 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 uses specific verb 'Compare' and resource 'AI visibility', clearly indicating it evaluates multiple entities side-by-side. It details the sub-steps (probes with ai_visibility_check, ranks, surfaces most/least recognized) and distinguishes itself from sibling tools like ai_visibility_check (single entity) by focusing on multi-entity comparison.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and a concrete example question. It implicitly suggests when to use (multiple competitors) but does not explicitly state when not to use or mention alternatives like ai_visibility_check for single entities. This is a minor gap.

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 read-only, idempotent, open-world. Description adds critical behavioral detail: partial failure handling, bundlephobia first measurement latency (5-30s), and listing failed sources. 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?

Long but densely informative; every sentence adds value. Could be slightly more concise but front-loaded effectively with purpose and use cases.

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 thoroughly covers return block structure, per-advisory details, links, alternative versions, and error behavior, making it complete for an agent to understand results.

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

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

Schema coverage is 100% with clear parameter descriptions. Description adds nuance (default version to latest, scoped packages accepted) but doesn't fundamentally extend beyond what schema already provides.

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 specifies a composite npm package evaluation (license, advisories, bundle size) and distinguishes from siblings by confining to NPM ecosystem v1, with clear fallback alternatives.

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 (agent asks about safety/popularity/size or cost) and provides exclusion criteria (non-NPM ecosystems go to deps.dev:version directly).

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

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

Annotations already declare safe, read-only, and idempotent behavior. The description adds value by specifying fuzzy name matching and the full set of returned fields, providing behavioral context beyond annotations.

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

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

Two sentences, front-loaded with purpose and filters, followed by output. No wasted words, 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?

The description covers filter options and output fields. Minor omissions like pagination and sorting are acceptable given no output schema and the tool's search nature.

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

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

Schema has 100% description coverage, baseline 3. The description adds extra meaning (e.g., 'fuzzy' for name, 'monster type/race' for race), improving parameter understanding without redundancy.

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

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

The description clearly states the action ('Search'), the resource ('Yu-Gi-Oh! TCG cards'), and the filter criteria (name, type, attribute, etc.). It also lists output fields, distinguishing it from siblings like 'get_card' and 'random_card'.

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 implies usage for multi-criteria card search but does not explicitly state when to use it versus alternatives or mention exclusion criteria. Sibling tools include 'get_card' and 'random_card', but no direct comparison is made.

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

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

Beyond annotations (readOnly, idempotent, openWorld, non-destructive), the description details embedding model (BGE-base-en), windowing (500-char overlapping), character cap (200K with truncation flag), and output format (passages with offsets and similarity scores). 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?

Dense but efficient: first sentence states purpose, second covers use case, third mentions pairing and offsets, fourth gives technical details. Every sentence adds value; 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 complexity (semantic search, offsets, truncation, pairing), the description covers all key aspects: what it does, when to use, how it works technically, and what it returns. No output schema is mentioned, but the description explains return value sufficiently.

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 context: clarifies text max length, provides query examples, and explains limit default. This enriches understanding beyond 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 specifies it performs semantic search inside a fetched record, with examples like SEC 10-K body. It distinguishes from sibling tools such as search_cards by focusing on internal search within a specific text.

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

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

Explicitly states 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded. Provides context for use but does not explicitly mention when not to use or alternatives beyond the pairing.

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 details behavioral aspects such as returning a new subscription id, requiring OAuth, supported event types, delivery channel behaviors (feed always on, email/SMS with limits, webhook auto-disable after 10 failures, HMAC signing). It does not contradict annotations; annotations indicate idempotentHint=true but description doesn't explicitly address idempotency, yet adds significant 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 a single paragraph but well-organized, starting with purpose, then requirements, types, and delivery. It is informative and every sentence adds value, though it could be slightly restructured for easier scanning (e.g., bullet points).

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 (nested objects, multiple types, delivery channels), the description covers all essential aspects: purpose, requirements, type specifications with examples, delivery options with constraints, and return value. No output schema is needed as the description clarifies the return value is the subscription id and webhook secret once.

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

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

Schema coverage is 100%, and the description enriches parameter meanings with concrete examples for each type (e.g., 'sec_8k' items:['5.02'] means officer change) and expanded explanations for delivery options (e.g., webhook signing secret returned once). This adds substantial 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 verb 'Create' and the resource 'proactive monitoring subscription to a live-data event stream', and it returns the new subscription id. It distinguishes from sibling tools like 'unsubscribe', 'list_subscriptions', and 'recent_alerts' by focusing on creation.

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

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

The description specifies requirements (Pipeworx OAuth account, not for anonymous/BYO), supported types with examples, and delivery channel constraints including email/SMS verification and rate limits. It does not explicitly contrast with alternative tools but provides enough 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 declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds that it returns category-bucketed example questions with exact tool+argument shapes from a live catalog, and positions it as an onboarding entry point—providing valuable context beyond the annotations.

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

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

The description is front-loaded with trigger phrases and is structured with categories in parentheses. While slightly verbose, every sentence adds value, and it avoids unnecessary detail.

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 adequately explains what the tool returns (example questions with tool+argument shape). It covers purpose, usage, and parameter details, making it complete for its simple onboarding role.

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

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

Schema has 100% description coverage on the single optional topic parameter. The description lists possible values (finance, pharma, etc.) which matches the schema description, adding no new semantic meaning beyond what's already in the schema.

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

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

The description clearly identifies this as the onboarding entry point for a new agent, listing trigger phrases like 'what can I ask' and 'getting started'. It distinguishes itself from siblings by stating to use it first when the agent doesn't know Pipeworx's capabilities.

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 this FIRST when you do not yet know what Pipeworx can do', providing clear guidance. It also explains the optional topic parameter to focus the output, though it doesn't explicitly mention when not to use it.

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

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

Discloses beyond annotations: ownership enforcement and row deactivation instead of deletion. No contradiction with annotations (destructiveHint false, idempotentHint true align with deactivation).

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 efficient sentences, front-loaded purpose, no fluff.

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

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

Complete for a simple 1-param tool with annotations: purpose, constraint, and behavioral effect are fully covered.

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 description of id as uuid from subscribe. Description adds no extra semantic 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?

Description clearly states 'Cancel a subscription by id' with a specific verb and resource, distinguishing it 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?

Provides ownership constraint and explains the deactivation behavior, linking to recent_alerts. While not explicitly stating when-not, the context is clear and no alternative cancel tool exists.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context: the dual processing paths (structured SEC EDGAR + XBRL vs. grounded pipeline), the exact output format (verdict, value with citation, reasoning), and the fact that it replaces 4-6 sequential 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 relatively long but well-structured. It front-loads with typical trigger phrases, then breaks down the processing logic and output. Every sentence contributes meaning, though it could be slightly more concise 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?

Given the complexity of the tool (two processing paths, multiple output fields), the description is remarkably complete. It explains the verdict types, citation format, and the tool's efficiency (replaces multiple calls). There is no output schema, so the description fully compensates by describing the return value.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds marginal value by explaining the tolerance_pct parameter's use cases (e.g., 'set 1–2 for hallucination detection'), but does not provide additional meaning for the 'claim' parameter beyond natural-language examples.

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: natural-language claim verification against authoritative sources. It provides specific trigger phrases (e.g., 'Is it true that', 'fact check', 'verify the claim that') and explains the two distinct processing paths for company financial claims vs. other claims. This distinguishes it from sibling tools like 'deep_research' or 'ask_pipeworx'.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It differentiates between claim types (company financial vs. other) but does not provide explicit when-not-to-use guidance. However, the context is clear enough for effective tool selection.

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