fruityvice

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds practical behavioral details: default model choice, cost implications of passing an API key, and the shape of the return value. This exceeds the annotation bar without contradicting 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 three sentences with no waste. It front-loads the core action, then covers model options and return format, and ends with use cases. Every sentence adds distinct value.

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

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

Despite no output schema, the description explicitly lists the per-model return structure and the combined view. It covers purpose, model selection, cost, and use cases, making it complete for the tool's complexity and parameters.

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 relational semantics beyond individual parameter descriptions: it clarifies that 'anthropic' requires '_apiKey' and that omitting 'models' defaults to workers-ai. This helps the agent understand parameter dependencies.

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: probing one or more LLMs and scoring visibility (0-100) per model. It specifies the resource (business/brand/product/topic) and distinguishes itself from sibling tools that are Q&A or competitor-analysis focused.

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

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

The description provides clear use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the default model vs. adding Anthropic with a key. However, it does not explicitly mention when not to use the tool or name alternative sibling tools.

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

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

Annotations already declare read-only, non-destructive, idempotent, and open-world. The description adds that it routes to thousands of tools, fills arguments automatically, and returns structured answers with citation URIs. It also notes it works on every tier and is a single fast call. This provides useful behavioral context beyond the annotations.

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

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

The description is well-structured, front-loading the 'prefer over web search' directive and then bullet-pointing domains and examples. It is longer than minimal but each section earns its place, from use-case list to alternative guidance. It could be trimmed slightly but remains readable.

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 (router, many sources, no output schema), the description covers purpose, usage, behavior, and examples. It explains the output format (structured answer with citations) and gives five concrete example queries. Nothing essential for an agent to decide whether to call it is missing.

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

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

The schema describes all six parameters with 100% coverage, including aliases. The description adds no additional parameter-specific semantics; the parameter 'question' is self-explanatory and the aliases are already listed in the schema. 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 it is a router that answers factual questions from verified sources, returning structured answers with citations. It lists many domains and gives examples, and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research. This makes its purpose unambiguous.

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

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

It explicitly says to prefer this over web search for factual queries, and provides a long list of use cases. It also instructs when to step up to ask_pipeworx_grounded or deep_research, giving clear when/when-not guidance. This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable context: it clarifies that this is a full working router with no fallback, confirms that currently no candidate is active so it matches ask_pipeworx exactly, and explains the experimental purpose. This goes beyond the annotations and provides a complete picture of behavior 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 moderately verbose but every sentence carries essential information: beta status, relation to ask_pipeworx, current procedure state, usage instruction, and functionality assurance. It is front-loaded with the key point (identity with ask_pipeworx) and well-organized. It could be tightened slightly without losing meaning, but it is not bloated.

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

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

For a simple one-parameter router with read-only, idempotent annotations, the description is quite complete. It explains the tool's role, current behavior (identical to ask_pipeworx), usage guidance, and that it returns the same response shape as ask_pipeworx. Without an output schema, that reference is sufficient. There is no critical missing information for correct invocation.

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

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

The input schema has 100% coverage; every parameter (question and its five aliases) is described as an alias for question. The description mirrors this by stating 'same arguments' but adds no additional semantic detail. Since the schema fully documents the parameter, the baseline of 3 is appropriate—the description neither harms nor enhances parameter understanding.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router that takes a natural language question and routes to one of 5,621 tools. It explicitly mentions the resource (pipeworx) and the verb (ask), and distinguishes itself from the stable ask_pipeworx by its experimental routing status. This makes the purpose unmistakable.

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

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

The description gives explicit guidance: use it exactly like ask_pipeworx when you want the newest routing, and notes it is the experimental edge. It implies the stable ask_pipeworx is the alternative for production, and explains that results are compared against the stable router. It does not explicitly state when NOT to use it, but the intent is clear enough for an agent to infer the appropriate context.

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

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

The description discloses detailed behavioral traits beyond annotations: it returns specific refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), provides verbatim evidence quotes, and only uses the tool result. It also notes the extra LLM call cost, adding context not covered by readOnlyHint, openWorldHint, idempotentHint, or destructiveHint.

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 ('Hallucination-resistant answer mode') and each sentence adds necessary detail: routing, extraction behavior, return format, refusal reasons, use cases, and cost. It is somewhat long but information-dense, with no wasted words; a slight verbosity keeps it from a 5.

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

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

With no output schema, the description fully specifies the return object (answer, evidence, confidence, source, fetched_at, refusal_reason) and all possible refusal reasons. It also explains the routing behavior and cost, making the tool complete for an agent to invoke and interpret results correctly. Nothing essential is missing.

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

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

The input schema has 100% coverage with descriptions for all six parameters. The description adds minimal meaning beyond noting the question is in natural language, which is already in the schema. Since schema descriptions are complete, the baseline of 3 applies; the description does not enhance parameter understanding beyond what is already structured.

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

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

The description clearly states the tool's purpose as a hallucination-resistant answer mode for high-stakes reads, explains it routes like ask_pipeworx but extracts answers strictly from tool results, and provides explicit use cases (financial verdicts, legal claims, medical lookups). It distinguishes itself from the sibling ask_pipeworx by emphasizing evidence extraction and refusal behavior.

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

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

Explicitly states when to use this tool (when answers will be quoted, cited, or acted on; when the agent must not invent facts) and when not to (casual lookups, prefer ask_pipeworx). It also mentions the cost trade-off of one extra LLM call, guiding the agent on tool selection.

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

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

The description goes far beyond the annotations (readOnlyHint=true, etc.) by disclosing numerous behavioral traits: resolver contract with confidence levels, low-confidence short-circuit behavior, closed-market status, wide-spread tradeability flags, news fallback mechanisms, and detailed cancellation-rule risk. It explains edge cases (e.g., de-indexed markets, 429 handling) and safety mechanisms, which is valuable context an agent would need.

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 clear section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It front-loads the core purpose and usage, then provides detailed, actionable information. While it could be trimmed, every section adds critical information that compensates for the lack of an output schema.

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

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

Given the tool's complexity and the absence of an output schema, the description is exceptionally complete. It covers the full resolution pipeline, all response shapes, edge cases (low-confidence, closed markets), safety mechanisms, and even resolution-rule risks. The agent has sufficient context to use the tool correctly and interpret results 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?

The input schema already covers 100% of the parameters, including descriptions for market, depth, and include_raw. The description adds examples and fan-out details but does not substantially enrich the meaning of the parameters beyond what the schema provides. Therefore, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet), the action (research/pull data), and the output (evidence packet + market-vs-model comparison). It also distinguishes itself from siblings by the explicit 'Use for...' guidance and the detailed fan-out examples.

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 scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides concrete examples of when to invoke it (e.g., BTC bet, Fed bet, Hormuz bet). However, it does not explicitly state when not to use this tool or name alternative sibling tools, so it falls short of a 5.

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

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

With annotations already indicating a safe read-only operation, the description adds valuable context: data sources (SEC EDGAR/XBRL, FAERS), fiscal-year handling, sorting by primary metric, and citation URIs in the return. This goes well beyond the annotations and fully discloses the tool's behavior.

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

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

The description is a single dense paragraph that front-loads purpose and usage. Every sentence provides useful information (trigger phrases, data sources, sorting, value proposition), with no filler. It is longer than a minimal description, but the complexity justifies the length.

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

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

Despite having no output schema, the description explains the return format ('paired data + pipeworx:// citation URIs per entity') and sorting behavior. It covers both entity types comprehensively, making it complete for an agent to invoke and interpret results.

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

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

Although the schema already covers 100% of parameters, the description adds meaningful semantics: it explains the type-specific meaning of 'values' (tickers/CIKs for company, drug names for drug) and provides concrete examples like AAPL Sep, NVDA Jan. This enhances 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 a specific verb+resource+scope: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It distinguishes itself from sequential lookups by emphasizing the parallel call and explicitly listing trigger phrases that indicate when users intend 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 explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' which is clear when-to-use guidance with an alternative. However, it does not mention when not to use the tool (e.g., for more than 5 entities or when deep analysis is needed), leaving 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 only declare readOnly, openWorld, idempotent, and non-destructive. The description adds rich behavioral context: it never invents answers, returns gaps[] for unanswered facets, includes contradictions[] for standard/thorough, provides stable pipeworx:// citations always fetchable, and notes timing (15-60s, up to ~90s for thorough). It also explains the hop field and excerpting of large records, far beyond what annotations provide.

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

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

The description is long but every sentence carries essential information, and the most critical items (account requirement, unpaid alternative) are front-loaded. The structure flows from prerequisites to core functionality to depth specifics to timing, all without redundancy.

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

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

For a tool with no output schema, the description fully explains the returned findings packet (evidence, confidence, source, fetched_at, citation, gaps, contradictions) and the hop field. It also covers timing expectations and the conditions under which citations are present, making it complete for an agent to invoke correctly.

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

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

Schema already documents both parameters with 100% coverage, so the baseline is 3. The description adds nuance about depth behavior (e.g., thorough chases the best leads from the first pass, multi-step questions resolve in one call) and reinforces that question is natural language, adaptable to broad/multi-part queries. This adds meaningful value beyond the schema.

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

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

The description states a specific verb and resource: it performs grounded multi-source research across Pipeworx's 1472 structured data sources, decomposing questions and routing to parallel tools. It explicitly says 'this is NOT open-web search' and names ask_pipeworx as the alternative for single lookups and current news, so an agent can clearly distinguish it from siblings.

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

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

The description gives explicit conditions: if not signed in, use ask_pipeworx; for a single lookup, use ask_pipeworx; for breaking or colloquial current-news topics, prefer ask_pipeworx. It also states that 'thorough' depth requires a paid plan, scoping usage precisely.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds meaningful behavior beyond annotations by explaining the return format (top-N tools with names, descriptions, and full input schemas) and that results are directly callable without a second schema lookup. No contradiction with annotations.

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

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

The description is four sentences and front-loaded with the core purpose. Every sentence adds value, though the enumerated domain list is lengthy and could be trimmed, keeping it from a 5.

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

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

Despite having no output schema, the description fully explains what the tool returns (top-N relevant tools with names, descriptions, full input schemas, ready to call) and when to use it. It gives enough context for the agent to invoke it effectively without further lookups.

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

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

Schema description coverage is 100%, with all aliases (q, task, search, description) and limit documented. The description mentions 'top-N' but does not add semantic detail beyond the schema, so the 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 tool finds tools by describing the data or task, with a specific verb ('Find') and resource ('tools'). It distinguishes itself from sibling tools by being the meta-tool for discovery, using phrases like 'Call this FIRST' and listing covered domains.

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

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

Provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This distinguishes it from direct-answer tools and implies 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?

Beyond annotations (readOnly/idempotent), the description discloses the parallel fan-out across sources, the soft-failure of the patents API, the GDELT→GNews fallback, and the required zero-padded CIK format. This is rich behavioral context that annotations alone do not provide.

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

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

The description is dense but well-organized, front-loaded with usage examples and a clear preference statement. Every sentence adds critical information, with semicolons effectively separating output fields and constraints.

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 enumerates all returned components (CIK, filings, fundamentals, patents, news, LEI) and their formats. It also covers error behavior (patents soft-fail) and input limitations, making the tool fully understandable for selection and invocation.

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

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

Although schema coverage is 100%, the description adds concrete examples for both parameters ('AAPL', '0000320193'), explains the zero-padding requirement, and clarifies that names are not accepted. This adds meaningful semantic detail 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 explicitly states the tool's function: building a full cross-source profile of a US public company, with concrete example queries. It clearly differentiates from siblings by recommending it over chaining single-pack lookups and referencing resolve_entity for name-based queries.

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

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

Provides explicit when-to-use guidance ('ALWAYS PREFER over chaining...') and when-not-to-use ('names not supported... use resolve_entity first'). The example queries make invocation scenarios unmistakable.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context by specifying it operates on 'previously stored memory' and can 'clear sensitive data', which justifies the destructive nature. No contradiction, and it provides additional value 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 only two sentences, front-loaded with the core action and followed by concise usage guidance. Every word earns its place; no filler or redundancy.

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

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

For a simple one-parameter tool, the description covers purpose, usage conditions, and related tools, while the schema and annotations cover the parameter and safety profile. No output schema is needed, and there are no gaps that would confuse an agent.

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

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

Schema coverage is 100%, with the 'key' property described as 'Memory key to delete'. The description reinforces this by saying 'by key' and 'previously stored memory by key', adding slight nuance that the key refers to an existing stored memory. This adds a bit beyond the schema's minimal 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 opens with 'Delete a previously stored memory by key', which is a specific verb (delete), resource (memory), and qualifier (by key). This clearly distinguishes it from siblings like 'remember' and 'recall' while naming them explicitly.

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 conditions: 'context is stale, the task is done, or you want to clear sensitive data'. It also references alternatives ('Pair with remember and recall'), offering both usage context and tool relationships.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description adds valuable behavioral detail: it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also discloses the output is a 'single text blob ready to drop at site-root/llms.txt', which is beyond the annotations' safety hints. 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 four sentences, front-loaded with the core purpose. Each sentence earns its place: purpose, process, output format, and use cases. There is zero fluff or redundancy. The structure is clear and scannable.

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 only 2 parameters and no output schema, the description is complete. It covers the input (URL), the process (fetch/extract/emit), the output format (standard llms.txt markdown), and practical use cases. No critical gaps for an agent to invoke it correctly.

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

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

The input schema already provides 100% coverage with descriptions for both 'url' and 'max_links'. The description adds little beyond 'any URL' for the 'url' parameter and doesn't mention 'max_links' at all. Since schema coverage is complete, a baseline score of 3 is appropriate, with no meaningful additional semantics from the 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 opens with 'Generate a production-ready llms.txt file for any URL', which is a specific verb+resource that clearly identifies the tool's purpose. It distinguishes itself from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing on generating the actual llms.txt file rather than just auditing or checking visibility.

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 'Useful for:' scenarios (getting a client's site indexed, drafting for your own project, auditing a competitor), giving clear context on when to use the tool. However, it doesn't explicitly mention alternative tools or when not to use it, so it stops short of full comparative guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is established. The description adds the scoping behavior (nutritional range filtering) but no additional details like return format or pagination. This is adequate but not rich.

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 concise sentences, front-loaded with the core action and resource, followed by the filtering specifics. There is no verbose or redundant wording.

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

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

For a simple read-only tool with three required parameters and an output schema, the description covers the operation and input guidance adequately. The minor nutrient naming discrepancy is a small gap, but the description is otherwise complete.

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

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

Schema description coverage is 100%, so each parameter is already well-documented. The description reiterates the nutrient types and min/max values but adds little new meaning. There is a minor inconsistency: description says 'carbs' while schema says 'carbohydrates'.

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

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

The description clearly states 'Find fruits matching a nutritional range' with a specific verb and resource, distinguishing itself from siblings like list_fruits and get_fruit by focusing on nutritional filtering. It precisely conveys the tool's purpose and scope.

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

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

The description provides clear context: use this tool when you need fruits filtered by nutrient type and min/max values. It does not explicitly mention alternatives or exclusions, but the intended use case is well implied through the filter specification.

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 establish read-only, idempotent, and non-destructive behavior. The description adds value by disclosing the exact return fields (calories, protein, fat, carbs, sugar, fiber per 100g) and providing examples. 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?

A single, front-loaded sentence states the purpose, return data, and examples. Every word contributes; no filler or redundancy.

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

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

Given the tool's simplicity (one parameter) and the presence of an output schema, the description adequately covers what the tool does and returns. It also handles the open-world hint appropriately by providing examples rather than an exhaustive list.

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

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

Schema coverage is 100% with a clear description for the 'name' parameter. The description's examples ('apple', 'banana') reinforce but do not add meaning beyond the schema, so it meets the baseline without exceeding it.

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

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

The description uses a specific verb and resource ('Get nutritional facts for a specific fruit') and clearly distinguishes from sibling tools like list_fruits and get_by_nutrition by specifying it targets a single named fruit and returns a defined set of nutritional fields.

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 retrieving details of a specific fruit, and the phrase 'for a specific fruit' differentiates it from listing or nutrition-based search tools. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds context beyond annotations by specifying the return fields (name, calories, protein, fat, carbs, sugar, fiber) and the scope 'all available fruits', which is useful behavioral information not present in the annotations.

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

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

The description is two sentences, front-loaded with the primary action, and every word earns its place. It efficiently conveys the tool's purpose and output without fluff.

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

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

Given the absence of parameters, the presence of a rich output schema, and comprehensive annotations, the description is completely adequate. It states what the tool does and what it returns, which is all an agent needs to invoke it correctly.

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

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

The tool has zero parameters, so the baseline for this dimension is 4. The description has nothing to explain about parameters, and the schema coverage is 100% (vacuously). No additional parameter documentation is needed.

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

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

The description clearly states the verb 'List' and the resource 'all available fruits', and specifies the nutritional profiles returned. This distinguishes it from sibling tools like get_fruit (which likely retrieves a single fruit) and get_by_nutrition (which likely filters by nutritional 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 for retrieving the full inventory of fruits, but it does not explicitly mention when to use alternatives such as get_fruit or get_by_nutrition. There is no direct 'when to use this vs. that' guidance, though the phrase 'all available fruits' suggests it is the canonical listing tool.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's job is lighter. It adds useful context by specifying the returned fields and implying only active subscriptions by default (aligning with the include_inactive parameter). No contradictions found.

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 action and return fields, followed by practical usage guidance. Every word earns its place; no redundancy.

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

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

For a simple read-only list operation, the description thoroughly covers what is returned, the default scope (active), and when to invoke it. No output schema exists, but the field list is provided directly, and annotations cover safety.

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

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

Schema description coverage is 100% for the sole parameter include_inactive, which already explains its behavior. The description doesn't add extra semantic detail beyond what the schema provides, earning the baseline score.

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 lists the caller's active subscriptions, enumerates the exact fields returned, and the action is distinct from sibling tools like subscribe/unsubscribe.

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

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

Explicitly provides two use cases: reviewing current monitoring before adding more subscriptions and finding an id to cancel. However, it doesn't name specific alternative tools or state when not to use it, so it falls just short of a 5.

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

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

With no annotations asserting safety (all false), the description takes full responsibility for behavioral disclosure. It mentions the claim_token mechanism for follow-up, rate limiting (5 per day), that it is free and doesn't count against quota, and that feedback signals affect roadmap. This goes well beyond the minimal requirements.

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

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

The description is longer than the minimal example but every sentence adds distinct value: purpose, usage triggers, exclusions, claim_token behavior, rate limits, and cost. It is well-structured and front-loaded with the core purpose, though slightly dense, preventing a perfect 5.

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

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

Despite lacking an output schema, the description explains the return behavior (claim_token, and passing it back to read resolution). It also covers rate limits, cost, and appropriate content guidelines. For a feedback tool with simple interactions, this is highly complete 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% with thorough descriptions for each parameter, so the baseline is 3. The description adds practical semantics for 'claim_token' by explaining how to use it to read status/fixes, and it clarifies that 'context' should reference Pipeworx tools/packs. This additional usage context elevates the score to 4.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It identifies specific feedback categories (bug, feature/data_gap, praise) and distinguishes itself from siblings like ask_pipeworx by focusing on reporting to the team rather than querying information.

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: only for tools served by this Pipeworx connection, and directs users to file elsewhere for other vendors' connectors.

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

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

Beyond the readOnly/idempotent annotations, the description adds valuable context: self-aggregating signal, derived from CF analytics-engine, no PII, and caching behavior (5min-1h depending on window). This exceeds what annotations alone convey.

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

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

The description is four sentences, front-loaded with the main purpose, then provides use cases and technical details. Every sentence earns its place without redundancy.

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

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

For a simple read-only tool with one optional parameter, the description covers return contents, use cases, data source, privacy, and caching. It is complete enough for an agent to select and invoke correctly.

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

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

The sole parameter 'window' is fully described in the schema (enum, default, meaning of shorter vs longer windows). The description mentions the windows too but adds no extra semantic beyond schema; 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 opens with 'What other AI agents are calling on Pipeworx right now' and states it returns top tools, top packs, and total call volume. This is a clear verb+resource statement that distinguishes it from sibling tools like ask_pipeworx or discover_tools.

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

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

The description includes a 'Useful for' section listing three concrete use cases (hot data sources, canonical tool confirmation, alignment check). This provides clear usage context, though it does not explicitly name alternative tools to avoid.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: the >3pp signal threshold, the Jaccard similarity anchor (≥0.30), the placeholder fraction cutoff (>20% returns null), and the fill-check caveat that 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it.' 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 dense but well-structured with clear headers (SEMANTIC ANCHOR, PARTITION FILTER, Response, FILL CHECK) and begins with the core purpose. It is longer than typical but every section provides functional details necessary for safe and correct use. A few thresholds could be embedded in the schema instead of prose, but overall the structure is excellent.

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 explicitly explains return values (opportunities[], partition_check fields, fill_check details) and edge cases (thin_legs, skipped_low_similarity, realizable_edge_pp). It also covers both single-event and cross-event modes thoroughly, and provides a pointer to the companion tool for custom sizing, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% for both parameters, so baseline is 3. The description goes far beyond the schema by adding concrete examples (e.g., 'fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), clarifying the behavioral differences between event and topic modes, and explaining why each mode is chosen.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from sibling tools like polymarket_fill_risk and polymarket_edges by detailing its unique scan modes (trending, event, topic) and precise analytical approach.

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

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

Explicit usage guidance is provided: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also names alternatives ('For custom sizing use polymarket_fill_risk') and explains when one mode is superior to another, e.g., 'Cross-event mode catches ... patterns that single-event misses.'

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

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

The description goes far beyond the readOnlyHint annotations, revealing response segment grouping, edge fields, funnel diagnostics, cache behavior ('Cached 1h at the KV level keyed on all knobs'), and unusual partition Kelly behavior ('min_kelly never filters them'). This gives the agent a strong mental model of both expected output and edge cases. No annotation contradiction.

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

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

The description is long but information-dense, with clear internal structure using numbered segments, labeled knobs, and response fields. It is front-loaded with purpose and use case, and every technical detail justifies inclusion. It loses one point for being a single dense wall of text that could benefit from more whitespace/breakouts.

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

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

Given the tool's complexity (9 optional parameters, no output schema), the description thoroughly covers return structure, edge metadata, diagnostics, cache behavior, and why segments can be empty. The agent gains enough context to call the tool and interpret results correctly without an output schema.

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

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

The input schema already provides 100% parameter descriptions, so the baseline is 3. The description adds extra meaning about how knobs interact, such as min_kelly never filtering partition arbs and min_liquidity/max_spread_pp dropping unrealizable edges. This supplements the schema with practical behavioral context, earning a 4.

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

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

The description opens with a specific verb-resource pair: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes this tool by its unique edge-detection purpose and detailed by_segment structure, making it easy to differentiate from related Polymarket tools.

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

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

It states an explicit use case: 'Built for "what should I bet on today"' and explains when Fed candidates are excluded due to unreliable signal. It does not name alternative tools, but the context is clear enough that an agent can infer when to apply it, even if exclusion guidance is implicit.

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

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

Annotations already mark the tool as read-only/idempotent, but the description adds significant behavioral context: response structure (tracked/expired/snapshot_dates), the meaning of data gaps (cache-miss days), and limitations (TTL bounds, daily closes vs intraday). No contradiction with annotations.

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

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

The description is longer than typical but exceptionally well-structured with ARGS, RESPONSE, and LIMITS sections, front-loading the core question. Every sentence conveys essential information, though a few details could be trimmed without losing meaning.

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

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

Without an output schema, the description fully specifies the three return fields (tracked, expired, snapshot_dates) and their interpretation, plus historical depth caveats. This is complete enough for an agent to invoke the tool and correctly understand the response.

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 a baseline of 3 applies, but the description adds semantic nuance by defining 'window' as a 'snapshot family' and clarifying that 'days' lookback aligns with the schema's clamp. It also connects parameters to the underlying snapshotting behavior, which is genuinely useful.

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's function as edge persistence and decay telemetry for polymarket edges, and frames the specific question it answers ('how long has this edge existed and is it shrinking?'). This distinguishes it from siblings like polymarket_edges, which presumably shows current edges only.

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

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

The description provides strong contextual guidance ('a fresh wide edge and a 3-week-old wide edge are different trades') and explains when the data would be relevant. However, it does not explicitly name alternative tools or state when not to use this tool, falling short of a 5.

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

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

The annotations provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description goes far beyond: it describes 'walks the ladder,' lists the return fields per mode, and discloses critical behavioral implications such as 'partial basket fills convert an arb into an unhedged directional position (the dominant loss mode).' No contradiction with annotations.

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

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

The description is a long, dense paragraph but well organized with clear SINGLE-MARKET and BASKET sections and a final usage directive. Every sentence carries essential information, though the length is high and formatting could be improved with bullets; still, it earns a strong score for 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?

Despite having no output schema, the description enumerates all return fields for both modes (e.g., theoretical_sum vs realizable_sum, capture_ratio, profit_usd, thin_legs, forced_directional_risk). It fully covers parameter behavior, usage context, risk scenarios, and ties to sibling tools, making it complete for a tool of this complexity.

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

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

The input schema has 100% description coverage, but the description adds substantial semantic nuance: size_usd is 'max spend on buys, target proceeds on sells' in single-market mode, and 'settlement notional S (shares per leg; each share pays $1)' in basket mode. It also explains default side behavior for both modes, enriching parameter meaning beyond the schema.

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

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

The description opens with a specific purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly defines two modes (single-market and basket) and describes the exact outputs (top_of_book, vwap_fill_price, slippage_pp, etc.), distinguishing itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk rather than signal 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?

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the reasoning (theoretical overround on thin books is not capturable, partial fills create unhedged directional risk), giving clear conditions 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?

Beyond the read-only/idempotent annotations, the description discloses rich behavioral details: the two operating modes, the meaning of compatibility_warning (including two specific trigger scenarios), temporal_alignment field semantics, and the skipped_cross_type/subtype counters. It explains what gets returned (spreads, safety fields) and why certain spreads are mathematically meaningless, far exceeding annotation coverage.

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

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

The description is lengthy but information-dense and well-structured, starting with the core purpose, then modes, response, and safety fields. It is front-loaded with the main verb and resource. However, it could be more concise—some sentences are complex and the final warning is repeated, so it doesn't score a 5.

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

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

Given the tool's complexity and the absence of an output schema, the description is highly complete: it explains return values (leg prices, spread.pp, compatibility_warning, temporal_alignment, skip counters), tradeability caveats, and operational nuances. An agent could reliably select and invoke this tool based on this description alone.

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

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

Although schema coverage is 100%, the description adds significant meaning by explaining how the parameters interact: 'topic' auto-fetches matching events via pre-mapped shortcuts, while explicit ticker/slug overrides the mapped sides. It clarifies the relationship between the three params and the two modes, which the schema alone does not convey.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It uses a specific verb ('spread') and resource (two named venues), and distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on cross-venue comparison with detailed mode explanations.

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

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

The description provides explicit when-to-use context by describing two modes ('topic' vs explicit ticker/slug) and detailed when-not-to-use cases: non-equivalent bet shapes (compatibility_warning), temporal misalignment (aligned:false), and the caution that pre-mapped topics are often not tradeable. It does not explicitly name alternative tools, which 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 readOnly, idempotent, and non-destructive behavior. The description adds valuable context about scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the memory lifecycle (remember to save, forget to delete), going beyond annotations.

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

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

Three sentences, each with purpose: action, use-case, and scope/lifecycle. Front-loaded with 'Retrieve' and 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 single-optional-parameter recall tool with no output schema, the description covers purpose, usage, scoping, and related tools. No gaps remain for an agent to misuse it.

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

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

Schema covers the key parameter 100% with a clear description. The tool description adds further value by explicitly stating the 'omit the key argument' behavior for listing all keys and providing example keys like user_research_topic.

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

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

The description uses a specific verb 'Retrieve' plus a resource ('a value previously saved via remember') and clearly distinguishes the list-all-keys behavior. It differentiates from siblings by naming remember and forget, and provides concrete examples of stored context.

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

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

States when to use the tool ('Use to look up context the agent stored earlier') and names related tools (remember, forget) for save/delete operations. It lacks an explicit 'when not to use' but gives sufficient context through 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 mentions that setting mark_read:true flags returned events as read, which is a side-effect (mutating read_at). However, the annotations declare readOnlyHint=true, implying the operation does not modify state. This contradicts the description's explicit statement about the mark_read parameter, so the description contradicts annotation. No credit for additional transparency because the contradiction is severe.

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 three sentences, front-loaded with the core purpose, and every sentence adds valuable information: return payload details, filtering options, mark_read behavior, and an alternative access endpoint. No filler or redundant phrasing.

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

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

Despite no output schema, the description explains what returned events carry (source, citation_uri, raw payload), the effect of mark_read, and the availability of the feed via HTTP. It covers the main parameters and use contexts, making it complete enough for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics: it gives an example for type ('sec_8k'), explains that since is an ISO timestamp, and details the behavior of mark_read (flagging reads so the next call only shows newer events) and unread_only (filtering on null read_at). This goes beyond the schema's brief parameter descriptions.

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

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

The description clearly states the verb 'Pull' and the resource 'fired events from your subscription feed', and specifies it returns the most recent alerts with details like source and citation_uri. This makes the tool's purpose distinct from sibling tools like list_subscriptions or subscribe, which handle subscription management rather than event retrieval.

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

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

The description provides clear context for when to use the tool: polling the feed, with an explicit note that 'Polls work fine' and an alternative access method via the HTTP endpoint for scripts/dashboards. It does not explicitly state when not to use it, but the alternative is a useful guideline for non-interactive use cases.

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

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

Discloses fan-out to multiple sources, GDELT→GNews fallback, PatentsView sunset soft-fail, and return structure. Adds significant behavioral detail beyond the readOnlyHints 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?

Slightly long but every sentence carries essential operational detail. Front-loaded with user-intent examples, then system behavior, then return structure.

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

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

For a complex multi-source tool with no output schema, the description thoroughly covers input formats, fallback logic, failure modes, and output shape. Leaves no major gaps.

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

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

Schema already covers 100% of parameters, so baseline is 3. Description adds value with relative date examples and accepted formats for 'since' and 'value', going beyond the schema descriptions.

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

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

Description identifies a specific action ('change feed') and resource ('company in last N days/weeks/months'), with example queries. It explicitly contrasts with entity_profile, distinguishing itself from a sibling.

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

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

Provides explicit when-to-use guidance via query patterns and states 'Use entity_profile instead' for static profiles. Clear context that this tool is for dynamic changes over a window.

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

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

Beyond the annotations (idempotent, non-destructive), the description adds meaningful behavior: the key-value pair is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours. This provides useful persistence semantics not available in the annotations.

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

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

Three sentences cover purpose, usage, and persistence details without waste. The pairing note is compact. Every sentence contributes new 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 being a simple tool, the description covers the core functionality, storage scope, retention policy, and companion tools. There is no output schema, but none is needed for a write operation. The information is sufficient for an agent to select 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% with descriptive parameter names and examples. The description adds minimal extra meaning beyond saying 'stored as a key-value pair', which is already implied by the schema. Baseline 3 is appropriate since the schema carries the semantic load.

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

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

The description opens with a specific verb and resource: 'Save data the agent will need to reuse later'. It clearly distinguishes the tool from siblings by explicitly mentioning companion tools 'recall' and 'forget', establishing this tool's role as the write operation in the memory trio.

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

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

Explicit usage guidance is provided: 'Use when you discover something worth carrying forward...' and examples like 'a resolved ticker, a target address'. It also directs pairing with 'recall' and 'forget', which clarifies when to use this tool versus its 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 goes well beyond annotations (readOnlyHint, idempotentHint) by detailing cascading lookups, graceful degradation when GLEIF/OpenFIGI unavailable, listing unresolved identifiers explicitly, and explaining cross-source identity spine. This adds rich behavioral context not captured in structured fields.

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

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

The description is long but front-loaded with example queries and usage guidance. The detailed explanations of company and drug types are necessary for correct usage, though some sentences (e.g., LEI enrichment details) could be slightly tighter. Structure is logical and not wasteful.

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 identifiers, cascading lookups, no output schema), the description is exceptionally complete. It covers input variations, output expectations, edge cases (graceful degradation, unresolved identifiers), and even mentions replacing manual lookups. An agent can fully understand behavior without needing additional documentation.

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

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

Schema coverage is 100%, but the description adds substantial meaning: for 'company' it explains returned identifiers (CIK, ticker, LEI with ownership, FIGI) and input types (ticker, CIK, ISIN, name). For 'drug' it details RxCUI, ingredient, brand, and citation. This goes far beyond the schema's brief enum and string 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 resolves a name to canonical/official identifiers, with specific example queries like 'what's the ticker for...'. It also explicitly says 'Use FIRST whenever you have a name but need an ID', distinguishing it from sibling tools like compare_entities or entity_profile.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains supported entity types (company, drug) and that the tool replaces 2-3 manual lookups, implying it's the primary resolution tool. No explicit when-not-to-use, but the context is clear.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description adds meaningful behavioral detail: it probes each entity with ai_visibility_check, ranks by score, highlights most/least recognized, and returns ranked list with score, confidence, and signal density. 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 front-loaded with the main verb and packs purpose, mechanism, use case, and output into four sentences. There is slight redundancy between 'ranks by score' and 'Returns ranked list', but otherwise every sentence earns its place with no unnecessary filler.

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

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

Given the rich input schema and annotations, the description is complete enough: it explains the multi-entity comparison, the probing mechanism, a realistic use case, and the exact return fields. It appropriately leaves schema-specific details like _apiKey conditionality to the schema description.

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

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

Schema description coverage is 100%, and all four parameters have thorough descriptions (e.g., models, _apiKey, context, entities). The tool description adds no parameter-specific semantics beyond what the schema already documents, so it meets the baseline for well-covered schemas.

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 'Compare AI visibility across multiple entities side-by-side', a specific verb+resource+scope that clearly distinguishes it from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison). It also explains the ranking and output, making the purpose unambiguous.

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

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

It provides clear context with 'Useful for competitive AI-marketing audits' and an example query. It references ai_visibility_check as the underlying probe, which implies single-entity usage goes to that sibling, but it does not explicitly state when not to use this tool or name direct alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context beyond annotations: partial failures degrade gracefully, first bundlephobia measurement may take 5-30 seconds, and sources_failed will list timeout sources. This covers latency and failure behavior, which is beyond what annotations provide. 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 relatively long but every sentence is informative. It is front-loaded with the main purpose, then covers usage, return details, ecosystem scope, and failure handling. It could be slightly more concise but is not wasteful; structure is logical and scannable.

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

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

Since there is no output schema, the description carries the burden of explaining return values. It lists the summary block fields (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), per-advisory details, links, and recent versions. It also covers partial failure and latency. This is complete for a tool of this complexity.

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

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

Schema covers 100% of parameters (package and version) with descriptions. The description does not add additional parameter details beyond the schema, so baseline 3 is appropriate. It mentions 'recent alternative versions' in the output but not parameter semantics.

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 its purpose: a composite npm package evaluation check via deps.dev and bundlephobia. It uses a specific verb ('check') and resource ('npm package'), and explicitly lists the data sources and output. It distinguishes itself from siblings by focusing on npm dependency evaluation, a unique niche among the listed tools.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"', providing clear when-to-use guidance. It also names the alternative for non-npm ecosystems: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly', which serves as a when-not-to-use clause.

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 embedding model details (BGE-base-en, cosine similarity), window size (500-char overlapping), a 200K character cap, and the truncation behavior (truncated and flagged). These behaviors go well beyond the annotations' read-only/idempotent hints and inform the agent about operational limits and output characteristics.

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

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

The description is compact yet information-dense, front-loaded with the core action, followed by the use case, companion tool, and technical details. No filler or redundant phrasing; each sentence contributes distinct value.

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

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

Given the absence of an output schema, the description adequately covers return values (passages with offsets and scores), constraints (200K char cap, truncation), and usage context. It also ties into sibling workflows, making it fully self-contained for an agent selecting and invoking the tool.

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

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

The input schema already covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds extra semantics by giving concrete examples for text and query, clarifying the niche use case, and explaining the offset/similarity output, which enhances understanding beyond the schema.

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

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

The description clearly states the tool performs semantic search inside already-fetched text, with specific examples (SEC 10-K, article, tool result) and expected outputs (top-N passages with offsets and similarity scores). It differentiates from sibling tools like ask_pipeworx_grounded by positioning search_within as the step that operates on text you already pulled.

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 to use this when the record is too big to fit in the prompt, and it names ask_pipeworx_grounded as a companion tool, explaining the intended workflow: fetch with the gateway, then ground over relevant passages. This gives clear when-to-use and how-it-fits guidance.

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

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

Annotations already indicate a write operation (readOnlyHint=false), open-world side effects, and idempotency. The description adds valuable constraints: account requirement, SMS verification and 10/day cap, and the always-on feed behavior. Does not contradict annotations, though webhook details (signing secret, auto-disable) are omitted from the description but present in the schema.

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

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

The description is dense but well-organized: purpose, supported types with examples, then delivery channels. It is three long sentences with no fluff; could be slightly more scannable, but every sentence earns its place.

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

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

For a complex tool with 3 params, nested objects, 5 supported types, and delivery options, the description covers the main usage scenarios well. It lacks webhook details (though in schema) and does not specify output format beyond the ID, but given no output schema, it is reasonably 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%, but the description adds concrete examples for each type (e.g., items:["5.02"] = officer change, topic:"fed", series_id:"UNRATE") that make parameter usage much clearer. Delivery channel semantics are also enriched with requirements and numeric caps.

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 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource. It distinguishes from sibling tools like list_subscriptions and unsubscribe, and even mentions the return value (subscription id).

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

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

Provides clear context for when to use (proactive monitoring), prerequisites (requires Pipeworx OAuth account, anonymous+BYO cannot persist), and how to consume the feed via recent_alerts or the registry URL. Does not explicitly state when NOT to use or contrast with alternative one-off query tools, but the guidance is strong.

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

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

Annotations already cover safety (read-only, idempotent, non-destructive). The description adds meaningful behavioral context: the output is a set of example questions categorized by domain, drawn from the live catalog, and each includes the exact tool+argument shape. It also explains the behavior of omitting vs providing a topic. 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 long but every sentence earns its place: it opens with natural user-phrase examples, then outlines the return structure, parameter behavior, and first-use guidance. It is front-loaded and dense with useful information, not padded.

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

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

Even without an output schema, the description fully covers what the tool returns (category-bucketed example questions, exact tool+argument shape), when to use it (first connect), how to focus it (topic), and how it relates to sibling tools. Annotations handle safety, making this highly 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 already describes topic and lists valid values. Description adds concrete examples ('finance', 'pharma', 'betting') and clarifies the effect of omitting topic ('cross-category spread'), which goes beyond the schema. Schema coverage is 100%, so the baseline is 3; the added examples and usage nuance push it to 4.

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

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

The description clearly states the tool is the onboarding entry point for learning what Pipeworx can do, returning category-bucketed example questions with the exact tool and argument shape. It distinguishes itself from sibling tools like ask_pipeworx and entity_profile by explicitly saying 'Use this FIRST' and framing it as a discovery/onboarding aid.

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 usage timing: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Names specific alternatives (ask_pipeworx, entity_profile, compare_entities) and explains when to use no arguments vs pass a topic. This is strong guidance beyond simply stating what the tool does.

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

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

The description goes beyond annotations by disclosing ownership enforcement and the deactivation (soft-delete) behavior, including the side effect that historical events stay available via recent_alerts. This adds meaningful behavioral context not present in the annotations.

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

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

The description is two sentences, front-loaded with the primary action, and each sentence contributes valuable information without redundancy or fluff.

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

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

The tool is simple (one parameter, no output schema), and the description covers purpose, ownership constraint, and behavioral outcome. It does not mention return values or error handling, but given the low complexity and strong annotations, the description is sufficiently complete.

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

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

Schema coverage is 100%, with the parameter id already described as 'Subscription id (uuid) returned by subscribe.' The description reinforces the parameter usage ('by id') but does not add significant new semantics beyond the schema.

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

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

The description states a specific action: 'Cancel a subscription by id.' It clearly identifies the resource (subscription) and method (by id), and the context of deactivation distinguishes it from related tools like subscribe and list_subscriptions.

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

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

The description provides clear context on when to use the tool: ownership is enforced (only cancel your own subscriptions) and the soft-delete behavior means historical events remain available via recent_alerts. It does not explicitly name alternative tools, but this context sufficiently guides usage.

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

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

The description goes well beyond the readOnly/openWorld/idempotent annotations by disclosing the two execution paths, the verdict taxonomy, the meaning of could_not_verify with verification_error{stage,detail}, and the distinction between could_not_verify and unsupported. It also warns callers about the interpretive pitfall of could_not_verify, adding context that annotations cannot convey. No contradiction exists.

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

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

The description is dense but well-structured: it starts with natural-language trigger phrases, states the use case, explains the two routing paths, lists verdict types, and clarifies error semantics. Every sentence conveys necessary information for correct invocation and interpretation, with no fluff. The formatting (semicolons, line breaks) aids readability.

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

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

This is a complex tool with multiple execution paths, a rich verdict set, and error semantics. The description covers the full behavior: what it verifies, how it routes, what it returns (verdict + value + citation + reasoning), and how to interpret edge cases (could_not_verify vs unsupported). Without an output schema, it effectively documents return values. It even notes the integration benefit of replacing multiple calls. Very 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?

The input schema already provides full descriptions for both parameters (claim, tolerance_pct) with examples and constraints, so baseline is 3. The tool description adds only marginal param-related context beyond the schema, such as the default tolerance cap of 5%, which is already in the schema. Therefore, it does not meaningfully elevate understanding beyond the structured fields.

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 natural-language examples and clearly states the tool's core function: natural-language claim verification against authoritative sources. It distinguishes between company-financial claims (SEC EDGAR/XBRL path) and any other factual claim (grounded pipeline), and notes it replaces 4–6 sequential calls, making its purpose and scope unmistakable.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides conditional routing (company-financial vs. other claims) and clarifies when the tool returns could_not_verify vs unsupported. However, it does not name alternative tools or explicitly state when not to use this tool, preventing a 5.

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