wger

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

The description adds valuable context beyond the annotations: the default model (Workers AI Llama-3.3-70b) is free, while probing Anthropic requires a BYO key and direct payment. It also outlines the return structure per model. These details are not implied by the readOnly/openWorld/idempotent hints, so they enhance transparency.

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

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

The description is concise and front-loaded with a clear action verb. Every sentence adds value: purpose, default behavior, cost implications, return format, and use cases. It is information-dense without being verbose.

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

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

Despite having no output schema, the description explicitly details the per-model return object and the combined view. Combined with coverage of use cases, defaults, and costing, the description provides a complete picture for a tool with only 4 parameters and no complex nested structures.

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 has 100% coverage with detailed descriptions for all 4 parameters, including the free default and the `_apiKey` requirement. The description's mention of the default model and BYO key largely repeats the schema, adding little new parameter-level meaning.

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

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

The description clearly states what the tool does: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It is specific with verb and resource, but does not explicitly differentiate from sibling tools like scan_competitor_ai_presence, which might overlap in purpose.

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

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

The description provides concrete use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It clearly implies when to use the tool but does not offer explicit exclusions or alternatives, 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, idempotentHint=true, destructiveHint=false, so the agent knows it's a safe, non-destructive read operation. The description adds valuable behavioral context: it fills arguments automatically, routes to multiple tools, returns stable pipeworx:// citation URIs, and works on every tier. It doesn't explicitly discuss rate limits or failure modes, but the annotation coverage plus additional routing context justifies a 4.

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 packed with useful guidance and examples, but it is quite long and somewhat sprawling, with many lists and parenthetical examples. The key message ('prefer over web search, start here, step up only when needed') is front-loaded, but the sentence density is high. It earns its length through concrete examples and sibling differentiation, but it could be tightened without losing substance.

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-question fact-answering tool with one required parameter, the description is exceptionally complete: it covers domains, sources, citations, routing behavior, tier compatibility, fallback options (grounded and deep_research), and many examples. No output schema exists, but the description clearly explains what the tool returns (structured answer with citation URIs). It also accounts for edge cases like news/opinion queries. Contextually, this is thorough and leaves little unstated.

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

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

The schema has 100% coverage with descriptions for the primary 'question' parameter and five aliases (q, text, input, query, prompt), all explained as natural-language question inputs. The description adds substantial semantic value by explaining what kind of questions are appropriate and how the question gets processed (routed to tools, arguments filled, structured answer returned). Since one required parameter with aliases is fully documented and enriched by the description, this exceeds the baseline 3.

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

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

The description clearly states that ask_pipeworx answers factual questions about current or historical data across many specific domains (SEC filings, FDA, FRED/BLS, etc.) by routing to 5,529 tools across 1,455 verified sources, returning structured answers with stable citation URIs. It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as step-up alternatives and explicitly says it is the default entry point.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and provides detailed when-to-use guidance: use for factual questions about real-world entities/events/numbers, 'START HERE' default, and step up only when needed (ask_pipeworx_grounded for hallucination-resistant single answers with verbatim evidence, deep_research for broad/multi-part questions). It also handles edge cases like 'what's the world saying about X' by noting it routes to live news.

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 convey read-only, idempotent, open-world, non-destructive behavior. The description adds valuable context: it is a full working router, not a fallback stub, and it may run candidate routing improvements when active. It also notes the current no-candidate state, which is useful for understanding its behavior at runtime.

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 informative paragraph. It front-loads the key 'beta version of ask_pipeworx' message and then efficiently explains current status, usage, and comparison against the stable router. Slightly verbose but every sentence contributes a distinct point.

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

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

Given the tool's complexity (universal router with thousands of tools) and lack of output schema, the description is remarkably complete. It explains the routing role, the experimental nature, the current active state, how to use it, and the comparison process, leaving no major ambiguity.

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

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

The schema description coverage is 100% and already explains the 'question' parameter and its aliases. The description mentions that it shares the same arguments as ask_pipeworx but does not add new parameter-level detail; baseline 3 is appropriate given the schema covers everything.

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 variant of ask_pipeworx, specifying that it is a universal router with 5,529 tools and identical arguments/response shape. It distinguishes itself from the stable ask_pipeworx by highlighting experimental routing improvements and current behavior when no candidate is active.

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 tells the agent to use it like ask_pipeworx when the newest routing is desired, and explains that results are compared to the stable router to inform merges. It does not explicitly list when not to use it, but the guidance is clear and references the sibling 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 destructiveHint=false, but the description adds substantial behavioral context: it only uses the tool result content, returns a structured refusal with specific reasons when data doesn't answer, and costs an extra LLM call. 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 front-loaded with the key concept ('Hallucination-resistant answer mode'), and every sentence earns its place by covering behavior, usage, cost, return format, and refusal modes. Although longer than typical, the density of useful information justifies its length.

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

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

Despite having no output schema, the description fully specifies the return structure and refusal reasons. It also explains the internal routing and extraction process, making the tool's behavior predictable for high-stakes use. The description provides complete context for 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?

Schema coverage is 100% with all six parameters described as aliases for a natural-language 'question'. The description does not add parameter-level meaning beyond the schema, which is acceptable given the coverage; baseline 3 applies.

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

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

The description employs a specific verb ('answer mode', 'extracts') and a clear resource ('Pipeworx' tool routing across sources), and explicitly distinguishes from sibling 'ask_pipeworx' by its 'grounded' or 'hallucination-resistant' capability. It also details the return format and refusal conditions, leaving no ambiguity about what the tool does.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', and names the alternative for casual lookups: 'prefer ask_pipeworx for casual lookups'. It also notes the extra cost as a trade-off, enabling informed selection.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safe-read profile is known. The description adds extensive behavioral context beyond these: resolver confidence levels, low-confidence short-circuit behavior, blocking paths for closed/dead markets, illiquid wide-spread handling, news fallback fields, and cancellation-rule risk. This is rich, actionable transparency.

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

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

The description is long but highly structured with clear labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every sentence contributes technical detail essential for correct invocation, but the length is at the upper bound of what is 'appropriately sized'. The front-loaded purpose sentence helps orientation.

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 absence of an output schema, the description meticulously documents all relevant return shapes, resolver behavior, parent-event extraction, news fallback, safety statuses, and cancellation-rule risk. It covers edge cases (closed markets, low-confidence matches, wide spreads) that an agent would otherwise encounter blind.

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 each parameter (market, depth, include_raw) already described in the schema. The description doesn't add new parameter semantics beyond restating input formats (slug/URL/question) and providing examples, which are already in the schema. It meets the baseline but doesn't exceed it.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It also lists concrete use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and distinguishes itself from generic research tools by its market-resolution and fan-out 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?

Explicit usage guidance is provided: 'Use for...' gives clear triggers. The fan-out examples illustrate when each classifier/strategy applies, and the resolver contract warns about 'medium/low matches' guiding when to trust results. Though it doesn't name sibling alternatives, it provides sufficient context for when this tool is appropriate.

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 and idempotent annotations, the description reveals substantial behavioral details: parallel execution, data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. No contradictions with annotations; it adds rich context about how the tool operates.

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

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

The description is dense but well-structured, starting with query examples then core function, then type-specific details and return behavior. Every sentence adds value, though the paragraph is long. Front-loading the purpose and usage guidance makes it effective, so it earns a 4 rather than 5 only because it could be slightly more compact.

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 there is no output schema, the description explains what the tool returns ('paired data + pipeworx:// citation URIs per entity'), how results are sorted, and the specific metrics for each entity type. It covers all essential aspects for selection and invocation, including examples and edge cases like off-calendar fiscal years, making it 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?

Although the schema already covers both parameters at 100%, the description enriches their meaning: 'type' is explained with its enum values and what data each pulls, and 'values' is clarified with examples and constraints (2–5 tickers or names). This goes beyond the schema's basic descriptions, giving the agent a deeper understanding of how to populate them.

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: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It includes concrete query examples and specific data pulled for each type, and distinguishes itself from siblings by explicitly saying 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.'

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

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

Provides explicit guidance on when to use: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This directly contrasts with likely alternatives like entity_profile, making it clear this tool is for multi-entity comparisons, not single-entity lookups. The 'Replaces 8–15 sequential lookups' further reinforces its use case.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive behavior. The description goes far beyond annotations, covering return packet structure (evidence, confidence, source, fetched_at), gaps[] for unanswered facets, never-invents guarantee, depth-dependent hop behavior, contradictions[] scan, semantic excerpting, latency expectations, and stable pipeworx:// citations.

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 leads with account requirements and the most critical caveat, then systematically covers capability, usage boundaries, depth semantics, output format, and performance expectations. Despite density, information is organized logically with semicolons and parentheticals that improve readability.

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

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

Given the tool's complexity (1455 sources, 5529 tools, parallel routing), no output schema, and limited annotations, the description compensates fully. It specifies input expectations, output artifacts (findings packet, citations, gaps[], contradictions[]), edge cases (breaking news, unavailable topics), and operational constraints (time, paid tier). This is a complete operational specification.

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?

While the schema already documents both parameters with descriptions, the tool description adds significant value: it clarifies that thoroughly depth requires a paid plan, explains hop behaviors for standard vs thorough, states that broad/multi-part natural language questions are acceptable, and elaborates on the purpose of each depth level.

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 (research) and resource (Pipeworx's 1455 structured data sources), explicitly contrasting with open-web search. It also distinguishes this from sibling tool ask_pipeworx for single lookups.

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

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

Provides explicit when-to-use guidance ('Best for broad/multi-part questions'), when-not-to-use ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS prefer ask_pipeworx'), and an account prerequisite with fallback alternative. This is clear operational context.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's safety profile is clear. The description adds valuable behavioral context beyond annotations: it returns top-N relevant tools with names, descriptions, and full input schemas, and notes each result is ready to call directly without a second schema lookup. This sets accurate expectations 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 four sentences with no fluff. It front-loads the purpose, then usage context, then return-value details, then strategic advice ('Call this FIRST'). Every sentence earns its place, making it highly efficient.

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

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

Despite having no output schema, the description explains the return structure (names, descriptions, schemas with curated examples) and the appropriate use case. Given the tool's read-only, discovery nature and the richness of the parameter schema, the description is fully self-contained.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by enumerating example topic areas (e.g., 'SEC filings, financials, revenue, profit, FDA drugs...'), giving the agent concrete sense of what queries to use. This supplemental guidance earns 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: 'Find tools by describing the data or task.' It clearly distinguishes this meta-discovery tool from its domain-specific siblings by stating it returns ready-to-call tool schemas and advising to 'Call this FIRST' when exploring options. This makes the purpose unambiguous.

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

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

The description provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and lists many concrete domains (SEC filings, FDA drugs, etc.). It also recommends calling first when many tools are available. However, it does not explicitly state when not to use it or name specific alternatives, 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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe, non-mutating profile. The description adds significant behavioral context beyond these hints: it discloses parallel fan-out across multiple APIs, specific return value structure (up to 5 filings with pipeworx URIs, latest 10-K fundamentals), a known outage ('USPTO PatentsView API sunset May 2025 — soft-fails until reactivated'), and the GDELT→GNews fallback. This transforms the annotation-level safety hint into a richer execution model.

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

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

The description is a single dense paragraph but front-loaded with user-intent examples and key directives ('ALWAYS PREFER'). Every sentence adds value: input constraints, source fan-out, return fields, and failure behavior. It could be slightly more scannable with bullet points, but the content is compact and purposeful. Not a single word is wasted.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so explicitly (cik, recent_filings, fundamentals, patents, news, LEI) with relevant details like URI templates and sorting. The tool's complexity (multiple external APIs, fallbacks, input validation) is fully disclosed, making the description complete for both 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?

The schema itself covers both parameters fully, so the baseline is 3. The description adds meaning through concrete examples ('AAPL', '0000320193'), clarifies the zero-padded CIK format, and reinforces the 'names not supported' rule with a pointer to resolve_entity. This extra contextualization goes beyond the schema's property descriptions, but the core semantics are already present in the schema, so 4 rather than 5.

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 phrase: 'full cross-source profile of a US public company' and enumerates the exact sources and return fields (SEC EDGAR, XBRL, USPTO, news, GLEIF). The examples like 'tell me about X' and 'company profile for Microsoft' make the purpose unmistakable. It also implicitly distinguishes itself from siblings like resolve_entity (name lookup) and compare_entities (comparison) by focusing on a single holistic profile.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides clear exclusions: 'names not supported (use resolve_entity first if you only have a name).' This gives the agent concrete decision rules for when to use this tool versus 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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds usage context but no extra behavioral depth beyond the obvious deletion action. It does not mention what happens if the key doesn't exist or whether deletion is permanent, but the annotations sufficiently signal destructiveness.

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

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

Two concise sentences: the first states the core function, the second provides usage conditions and sibling pairing. Every word earns its place, no redundant content.

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

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

For a single-parameter, no-output-schema deletion tool, this is complete. It covers purpose, usage context, and relationship to sibling tools. The annotations fill in the destructive semantics, so nothing critical is missing.

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

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

Schema coverage is 100%: the only parameter 'key' is described as 'Memory key to delete'. The description's phrase 'by key' adds nothing 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 uses the specific verb 'Delete' with a clear resource ('a previously stored memory by key'), immediately distinguishing it from sibling tools like remember and recall. It also mentions these siblings explicitly, reinforcing its unique role in the memory workflow.

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 states when to use the tool ('when context is stale, the task is done, or you want to clear sensitive data') and even advises pairing with remember and recall, giving clear contextual guidance without needing to consult sibling descriptions.

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 the key behavior: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also explains the output as a 'single text blob ready to drop at site-root/llms.txt.' The annotations (readOnlyHint, idempotentHint, destructiveHint) cover safety, and the description adds process-level detail without contradicting those annotations.

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

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

The description is concise and front-loaded: the first sentence states the primary purpose, the second summarizes the process and output, and the final clause lists use cases. Every sentence adds value with no 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?

Given the tool's simplicity (2 params, no output schema), the description is sufficiently complete: it explains the input (URL), the process, the output format, and the practical applications. The annotations cover safety and idempotency. No major gaps remain, though it could mention edge cases (e.g., invalid URLs) but that is not critical for this straightforward generator.

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

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

Schema description coverage is 100%, with both 'url' and 'max_links' fully documented in the schema (including default and max values). The description adds little param-specific meaning beyond the schema, though it does explain the practical source of links ('extracts title/description/key links'). This meets the baseline for high schema coverage.

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

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

The description clearly states the action ('Generate a production-ready llms.txt file'), the resource ('for any URL'), and the specific output format ('standard llms.txt markdown'). It also lists concrete use cases (getting a client's site indexed, drafting for own project, auditing a competitor) which distinguishes it from sibling tools like ai_visibility_check and scan_competitor_ai_presence.

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

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

The description provides explicit use cases ('Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context for when to invoke this tool. It does not explicitly state exclusions or name alternative tools, but the guidance is specific enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which cover the safety profile. The description adds no additional behavioral context (e.g., error handling, caching, or existence requirements) beyond confirming it is a read operation. Since annotations carry the burden, a 3 is appropriate.

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, concise sentence that front-loads the action and resource. No unnecessary words or repetition.

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 has a single parameter, a rich output schema, and clear annotations. The description fully explains the tool's purpose and input requirement. There is no need for additional detail about return values or behavior since the output schema and annotations cover them.

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% parameter description coverage: 'The numeric wger exercise ID.' The description's phrase 'by its numeric ID' only restates what the schema already explains, adding no new meaning. Baseline 3 is applied.

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: 'Get detailed information for a specific exercise by its numeric ID.' It uses a specific verb ('Get'), identifies the resource ('specific exercise'), and distinguishes itself from sibling tools like list_exercises by focusing on individual items.

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 the appropriate use case (when you have a numeric ID and need details), which is clear context. However, it does not explicitly exclude alternatives like list_exercises or mention when not to use it, so it falls short of a full 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 read-only, idempotent, non-destructive behavior. The description adds 'Returns each item's numeric ID and name' and examples, which is useful but largely duplicates what the output schema likely provides. No extra behavioral context like ordering or completeness guarantees beyond 'all' is given.

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 exactly two sentences, front-loaded with the primary action and resource, and includes concrete examples without unnecessary padding. Every sentence adds value.

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

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

Given zero parameters, rich annotations, an output schema, and a simple list operation, the description fully covers the essential context: the resource domain, scope ('all'), and return contents. No critical information 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 tool has zero parameters, so there is nothing to describe. The baseline for zero-parameter tools is 4, and the description's 'all' confirms no filtering inputs exist, aligning with the empty input schema.

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

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

The description uses a specific verb ('List') and resource ('all gym equipment types in the wger database') and clarifies the returned data ('numeric ID and name'). This clearly distinguishes it from sibling list tools like list_exercises and list_muscles.

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 purpose implies the usage scenario (when you need gym equipment types), but it does not explicitly state when to prefer this tool over alternatives or when not to use it. No exclusions or alternative tool references are given.

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

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

Annotations already signal read-only and idempotent behavior, so the bar is lower. The description adds transparency about the default limit of 20 and the language filter (English), which are not evident from annotations or 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 two sentences, with the main action stated first and supplementary details (default count, return fields) following. Every word adds value 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 tool's simplicity (one optional parameter), rich annotations, and existing output schema, the description covers all essential aspects: purpose, scope, return content, and default behavior. No significant gaps remain.

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

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

The schema already covers the single 'limit' parameter with full coverage. The description reinforces the default value but introduces no new syntax or semantics beyond the schema, aligning with the baseline for high schema coverage.

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

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

Description specifies the verb 'List' and the resource 'fitness exercises from the wger database', with a clear scope (English, optional limit). It differentiates from siblings like get_exercise by indicating a list of entries with multiple muscle and equipment 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 provides clear context for when to use the tool (fetching a list of exercises from wger) and implicitly distinguishes it from more specific tools like get_exercise. It does not explicitly state exclusions or mention sibling alternatives, 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context beyond annotations: it states the tool returns all muscles with specific attributes (numeric ID, English name, front/back location) and covers the entire wger database. No contradictions with annotations.

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

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

Two concise sentences front-loaded with the primary action. Every word serves a purpose—scope, return fields, and location attribute. No redundancy or 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?

For a simple list tool with no parameters and comprehensive annotations, the description fully covers purpose, scope, and return fields. The presence of an output schema further reduces the need for additional explanation.

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 is 4. The description provides no parameter details (none exist) and focuses on return values, which is appropriate for a parameterless tool.

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 ('List') and resource ('all muscles tracked in the wger database'). It also specifies the returned fields (numeric ID, English name, front-of-body flag), making it distinct from sibling list tools like list_exercises and list_equipment.

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 makes the usage context clear—listing all muscles—but does not explicitly mention when to use this tool versus alternatives (e.g., get_exercise). Use case is implied, not explicitly contrasted.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds valuable context beyond these by specifying the scope ('caller's') and the exact fields returned, which helps set expectations. It does not contradict 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 and front-loads the core purpose before giving usage guidance. Every word earns its place, with no repetition of schema information 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?

For a read-only list tool with a single optional parameter and no output schema, the description is sufficiently complete. It covers the purpose, the return content, and the common use cases, which is everything an agent needs to know.

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 description coverage is 100%, as the single boolean parameter 'include_inactive' is fully documented in the schema. The description does not elaborate on this parameter, but the schema already does the heavy lifting, so a baseline score of 3 is appropriate.

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

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

The description uses the specific verb 'List' with the resource 'subscriptions', scoped to 'the caller's active subscriptions'. This clearly distinguishes it from sibling tools like subscribe and unsubscribe, and it also lists the returned fields, making the purpose unambiguous.

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

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

The description explicitly states when to use this tool: 'to review what you're monitoring before adding more or to find an id to cancel'. This gives clear context and helps an agent decide between this and the subscribe/unsubscribe 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?

Beyond the basic annotations, the description discloses rate limits (5 per identifier per day), the claim_token mechanism for follow-up, that it's free and doesn't count against quota, and how feedback is processed (daily digests). 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 dense paragraph packed with essential details. While front-loaded with purpose, it could be better structured into bullets or short sections for easier scanning. Every sentence earns its place, but readability suffers slightly.

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

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

For a 4-parameter tool with no output schema, the description explains what the response will be (claim_token) and the lifecycle of the feedback. It covers scope, limitations, and follow-up procedure, making it self-sufficient for the agent.

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

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

Schema covers 100% of parameters, but the description adds practical guidance: how to use claim_token (pass with no other arguments), what to avoid in the message (don't paste end-user prompts), and how to describe context in terms of Pipeworx tools/packs. This goes beyond schema descriptions.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly differentiates from sibling tools by focusing solely on feedback about Pipeworx tools, not on data retrieval or research.

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

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

Explicit when-to-use guidance is given (bug, feature/data_gap, praise) and a clear exclusion: 'ONLY for tools served by this Pipeworx connection... file it with that server instead.' It also tells users how to check if a tool is Pipeworx's.

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, open-world, idempotent, non-destructive behavior. The description adds valuable context beyond annotations: self-aggregating signal, derived from CF analytics-engine, no PII, and caching behavior (5min-1h). This fully discloses the tool's operational traits.

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

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

The description is four sentences, each contributing distinct value: what it does, what it returns, when to use it, and its data/caching characteristics. No redundancy or filler; it is front-loaded with the core purpose.

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

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

The tool has one optional parameter, no output schema, and rich annotations. The description covers return content (top tools, packs, volume), data source, privacy, and caching, which is fully sufficient for a simple, well-annotated read-only tool.

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

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

Schema coverage is 100% and the parameter description in the schema already explains the window enum and the trade-off between shorter and longer windows. The tool description repeats the same information without adding new semantics, so it meets the baseline expectation.

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 reports what other AI agents are calling on Pipeworx, returning top tools, packs, and call volume. It distinguishes itself from siblings like discover_tools by focusing on real-time aggregated usage, not generic 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?

Provides explicit use cases ('Useful for...') with three concrete scenarios, which is clear context for when to use the tool. It does not explicitly name alternatives or exclusions, but the listed use cases are sufficient guidance for most situations.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, but the description adds substantial behavioral detail beyond those: it discloses live CLOB depth fill-checking, specific thresholds (3pp deviation, 0.30 Jaccard similarity, 20% placeholder fraction), and the condition where realizable_edge_pp ≤ 0 means 'do not trade it'. It also mentions skipped_low_similarity and null signals, offering transparency without contradicting annotations.

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

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

Despite being long, the description is well-structured with uppercase section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and clear mode subheadings. Every sentence delivers operational detail, such as thresholds, response fields, and edge cases, with no repetition or filler. It is front-loaded with the core purpose and then systematically expands, making the length appropriate for the tool's complexity.

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

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

With no output schema, the description carries a heavy burden to explain returns, and it does so thoroughly: it specifies the response structure (opportunities[] with gap_pp, suggested_trade, reasoning, monotonicity context) and the partition_check fields in event mode. It also covers failure and edge cases (placeholder filters, low-similarity rejections, thin legs), leaving no ambiguity for an agent to invoke the tool correctly.

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

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

The input schema provides descriptions for both event and topic parameters, achieving 100% coverage, which sets a baseline of 3. The description enriches this by explaining the full behavior of each mode: event walks child markets and checks date/threshold ordering, while topic searches related events and flattens markets. It also notes that full Polymarket URLs are accepted, adding value beyond the schema.

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

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

The description opens with a specific, actionable statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly identifies the resource (Polymarket), the action (find arbitrage), and the method. It also distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by detailing distinct modes (trending_scan, event, topic).

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 instructions for each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also names an alternative tool for custom sizing: 'For custom sizing use polymarket_fill_risk.' This is clear when-to-use/not-use guidance, exceeding a typical description.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, yet the description adds substantial behavioral context: model family details, caching at KV level, diagnostics for empty segments, caveats about Fed signals being unreliable, and warnings that 'your edge may already be in the price.' This far exceeds annotation coverage and fully discloses 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 long but highly structured with clear sections (model families, knobs, response top-level) and every sentence adds value. It front-loads the purpose and provides detailed behavior without redundancy. 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?

There is no output schema, so the description carries the full burden of explaining return values. It thoroughly describes by_segment contents, fed_candidates/fed_note, diagnostics, and how filters affect results. It also covers caching and parameter interplay, making the tool fully understandable for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches parameter meaning by explaining the tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) in context of the response structure, and adds practical insights like slippage assumptions and 'set to 2 to require tight books.' This goes beyond the schema's descriptions.

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

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

The description clearly states a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also explicitly distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by describing unique output segments and the 'what should I bet on today' use case.

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 context with 'Built for "what should I bet on today"' and explains when to use it versus alternatives via detailed tradeable-edge knobs and filtering behavior. However, it does not explicitly name alternative sibling tools or state 'use this instead of X,' leaving some implicit guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses significant behavioral traits: snapshots are written on a cache-miss so gaps mean 'nobody scanned that day', history is bounded by a 60-day TTL, decay is computed from daily closes of edge_pp_net net of default slippage, and the value is signed by trade direction (negative = SELL YES). This is 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 dense but well-structured: purpose/analogy first, then args, then a detailed RESPONSE section, then LIMITS. Every sentence contributes valuable information (response field semantics, edge signing, snapshot gaps). The organization makes it easy to parse despite 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?

With no output schema, the description fully compensates by detailing the response shape: tracked[] with trend and decay metrics, expired[] with lifespan_days, and snapshot_dates[]. It also explains caveats like 60-day TTL and daily-closes basis, covering all major behavioral aspects of a moderately complex telemetry tool.

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

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

The schema covers both parameters completely with defaults and valid values. The description adds only trivial repetition (e.g., 'window (snapshot family, default "1wk")') and provides no additional syntax or format details beyond the schema. Since schema coverage is 100%, the baseline of 3 applies without further compensation needed.

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

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

The description states a specific purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers the question 'how long has this edge existed and is it shrinking?' This clearly distinguishes it from siblings like polymarket_edges (current edges) and polymarket_arbitrage.

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: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take).' It implies using this to assess edge age/decay before trading, but does not explicitly name alternatives or state when not to use it.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantive behavioral detail: it walks the ladder, returns fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; in basket mode it computes theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg fills, thin_legs[], max_clean_notional_usd, and forced_directional_risk. It also warns about partial fills converting an arb into an unhedged directional position, going well beyond the annotation safety profile.

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

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

The description is long but well-structured with uppercase section markers (REQUIRES, SINGLE-MARKET, BASKET) and front-loads the core purpose. Every sentence provides distinct information, though the length could be trimmed by removing some parallel phrasing between modes.

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

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

There is no output schema, so the description must enumerate return values; it does for both modes. It also covers defaults for side and size_usd, the clamp range, and the tool's intended place in the workflow relative to sibling tools. For a tool with 4 parameters, no output schema, and two distinct modes, the description is complete.

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

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

The schema has 100% coverage with detailed descriptions for each parameter. The description adds the critical constraint 'REQUIRES one of market (single-market mode) or event (basket/partition mode)' and clarifies size_usd's dual interpretation, though the schema already covers most parameter semantics. The added constraint is valuable for correct invocation.

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

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

The description opens with a clear verb-object: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes this tool from siblings like polymarket_arbitrage and polymarket_edges by focusing on whether theoretical edges are actually capturable on the order book.

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

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

The description explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround on thin books is not capturable, partial fills create directional risk). It names alternatives and provides a clear trigger.

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 readOnly, idempotent, and not destructive, and the description adds rich behavioral detail beyond that: compatibility_warning conditions, temporal_alignment implications, skipped_cross_type counters, and the explicit statement that 'aligned:false means spreads are mathematically meaningless across the temporal gap.' The description also discloses that 'real cross-venue spreads are rarer than the macro-shortcut list suggests.' This is transparent about edge cases and limitations, 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 long and dense, but each sentence delivers distinct information: core definition, modes, response fields, safety conditions, and caveats. It is logically structured (definition → modes → response → warnings). A slight deduction for verbosity; it could be tightened by trimming redundant clauses, but it earns its length given the tool's complexity.

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

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

With no output schema, the description fulfills the burden of explaining return values: leg-by-leg prices, matched spreads in percentage points, compatibility_warning semantics, temporal_alignment, and skip counters. It covers both success and failure modes (no matched pairs, skipped cross types). For a 3-param tool with no output schema, this is exceptionally complete.

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

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

Schema coverage is 100% with descriptions for all three params, but the tool description adds significant semantics by explaining the interplay: TWO MODES, where topic auto-maps both sides, and kalshi_event_ticker/polymarket_event_slug override individually. It also gives concrete examples ('fed', 'btc') and clarifies response structure tied to params. This goes well beyond the schema's property descriptions.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes the tool from siblings like polymarket_arbitrage by focusing on cross-venue comparison, not intra-venue arbitrage. The scope (same question, two venues) and the output (spread) are unambiguous.

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

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

The description explicitly outlines two usage modes (pre-mapped topics vs explicit tickers) and provides strong guidance on when the tool is reliable vs not: 'when the bet shapes are equivalent that delta is a real signal, when they aren't the tool says so.' It also warns that most pre-mapped topics currently return compatibility_warning, cautioning against assuming tradeability. It doesn't name alternative sibling tools, but the usage context is clear enough to avoid misuse.

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=false. The description adds valuable scoping context ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the list-all-behavior when key is omitted. It stops short of describing error cases, but annotation coverage lowers the bar.

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 action, then use cases, scoping, and sibling pairing. Every sentence contributes 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 and no output schema, the description covers purpose, usage context, scoping, and sibling relationships. It does not detail return formats, but the actions 'retrieve a value' and 'list all saved keys' sufficiently imply expected returns.

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

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

The input schema covers 100% of the single parameter with a clear description and example. The tool description merely restates what the schema already says ('omit the key to list all keys'), adding no new parameter-level 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 opens with a specific action: 'Retrieve a value previously saved via remember, or list all saved keys'. It clearly identifies the resource (saved memory values) and distinguishes from sibling tools by naming remember and forget.

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

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

Provides explicit when-to-use guidance with examples ('the user's target ticker, an address, prior research notes') and positions the tool among siblings via 'Pair with remember to save, forget to delete'. However, it lacks explicit when-not-to-use or alternative tool comparisons beyond remember/forget.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses a key behavioral trait: setting mark_read:true flags returned events as read, affecting future pulls (only newer events). It also reveals the feed is persisted and shared via an HTTP endpoint. This is valuable context not captured in 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 three sentences, front-loaded with the primary action ('Pull fired events'), and each sentence earns its place: purpose+returned fields, filtering+mark_read behavior, polling+alternative access. 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 no output schema, the description compensates by summarizing returned fields (source, citation_uri, raw event payload) and covers the main parameters with examples. It also addresses polling psychology and provides a programmatic alternative. Slight gap: doesn't mention limit or unread_only, but those are well-documented in the 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning by giving a concrete type example ('sec_8k'), explaining the 'since' filter as ISO timestamp with fired_at comparison, and detailing the side effect of mark_read:true on subsequent calls. This goes beyond the schema descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed, returns the most recent alerts with specific attributes (source, citation_uri, raw event payload), and distinguishes itself from siblings like list_subscriptions and recent_changes by focusing on alerts from the persisted evaluator feed.

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 usage context by noting 'Polls work fine' and offers an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts/dashboards, which helps choose between agent-polling and direct HTTP. However, it does not explicitly differentiate from sibling MCP tools or state when-not-to-use.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses the fan-out behavior to multiple APIs, the GDELT→GNews fallback on rate limits/5xx, and the USPTO soft-fail due to PatentsView sunset. This gives the agent a realistic model of failure modes and data source behavior without contradicting annotations.

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

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

The description is front-loaded with intuitive query examples, then succinctly covers data sources, parameters, return format, and the key alternative. Every sentence adds valuable information with zero filler, striking an appropriate length for the tool's complexity.

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

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

Although there is no output schema, the description fully explains the return structure (changes[] grouped by source, total_changes count, citation URIs). It also covers data source behavior, fallback, and edge cases (USPTO soft-fail), making the tool's behavior predictable in most situations.

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

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

Schema description coverage is 100%, so the schema already fully documents all parameters (type, value, since). The description adds no new parameter semantics beyond what the schema provides—it only repeats the since format and typical usage recommendation verbatim from 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 is a change feed for a company over a time window, with explicit example queries ('What's new with X', 'latest on Y'). It distinguishes itself from entity_profile by specifying when to use the static profile instead, and the mention of multiple data sources (SEC, GDELT/GNews, USPTO) makes the 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 gives concrete usage context through example queries and recommends the default `since` value ('30d' or '1m'). It explicitly names entity_profile as an alternative for static profiles, providing clear when-to-use vs. when-not-to-use guidance.

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

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

Annotations already indicate this is a non-read-only, idempotent write, but the description adds valuable context beyond annotations: key-value storage scoped by identifier, session-specific retention (24 hours for anonymous, persistent for authenticated). 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?

Every sentence provides distinct value: purpose, usage triggers, storage model, persistence behavior, and tool pairing. The structure is front-loaded with the core action and efficiently conveys necessary details without waste.

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

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

Given the tool's simplicity (two required parameters, no output schema), the description fully covers what an agent needs: what to store, when to use it, persistence semantics, and related tools. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats examples already present in the schema (e.g., ticker, address, preference) without adding new parameter-level meaning, so it does not exceed the baseline.

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

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

The description uses a specific verb ('Save data') and a clear resource ('data the agent will need to reuse later'), explicitly distinguishing it from siblings like recall and forget. It clearly states the tool's core function 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?

Provides explicit guidance on when to use it ('when you discover something worth carrying forward...'), and names companion tools ('Pair with recall to retrieve later, forget to delete'). Also clarifies persistence differences for authenticated vs anonymous sessions.

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: identifiers are source-labelled, unresolved items are stated explicitly, and LEI/FIGI enrichment degrades gracefully if upstream services fail. This goes 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 detailed but well-structured, starting with user-phrase examples, then purpose, then per-type breakdown. It's longer than average but every section adds substance for a complex tool; no filler.

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

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

With no output schema, the description adequately explains returns (source-labelled identifiers, unresolved list, RxCUI/brand/ingredient for drugs) and failure behavior (graceful degradation). It covers the two types and integration context, though an example response would make it fully 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%, so the baseline is 3. The description reinforces parameter meanings with examples (ticker, CIK, name for company; brand/generic for drug) but doesn't add significant new semantic information beyond the schema's property descriptions.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers with specific examples (ticker, CIK, LEI, RxCUI) and supported types. It distinguishes itself by noting it provides IDs required by other tools, differentiating it from siblings like entity_profile.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID' and notes it replaces 2-3 manual lookups, giving clear when-to-use guidance. It doesn't mention when not to use it or name alternatives, so it misses the 'when-not/alternatives' piece.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context: it invokes ai_visibility_check per entity, ranks results, and returns a specific structure (score, confidence, signal density). This goes beyond the annotations without contradicting them.

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

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

Two sentences, front-loaded with the main purpose. The first sentence states the action and process; the second provides the use case and return format. Every word earns its place, and there is no redundancy with the 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?

The tool has 4 parameters and no output schema, but the description compensates by specifying the output fields (score, confidence, signal density) and the invocation workflow. It covers the core behavior and use case sufficiently; minor details like error handling are absent but not critical here.

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

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

Schema description coverage is 100%, so the schema already documents all parameters, setting a baseline of 3. The description adds extra semantic value by explaining that the first entity is treated as the 'subject' for narrative, which is not in the schema. This justifies a score above baseline.

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

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

The description clearly states a specific action: 'Compare AI visibility across multiple entities side-by-side.' It details the process (probes each entity with ai_visibility_check, ranks by score) and the result (surfaces most/least recognized). This distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description gives a concrete use case ('competitive AI-marketing audits') and an example question. It implicitly differentiates from the single-entity sibling by emphasizing 'multiple entities side-by-side,' but it does not explicitly state when not to use it or name alternative tools for exclusion.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral detail: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts while the rest still returns. This goes beyond annotations and sets accurate expectations.

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

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

Single paragraph is information-dense and front-loaded with the core purpose and use case. It packs in many output field names and caveats, but each clause earns its place for a composite tool; minor lack of structural formatting 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?

No output schema exists, so the description compensates by listing exact summary fields, per-advisory detail, links, alternative versions, and failure behavior. For a complex multi-source read tool with two parameters, this is complete.

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

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

Input schema fully covers both params (package name with scoped support, version defaulting to latest). The description does not add significant new parameter semantics beyond the schema; it mostly restates the default and explains output fields, so baseline 3 is appropriate.

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

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

Description clearly states it is a composite check for deciding whether to add an npm package, aggregating license, advisories, version history, and bundle size from deps.dev and bundlephobia. This specific verb+resource+scope distinguishes it from generic scan tools like scan_competitor_ai_presence.

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 tells the agent when to use: 'Use whenever an agent asks...' and gives a clear exclusion for non-NPM ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), meeting the when/when-not bar.

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 (readOnly, idempotent, etc.), the description discloses algorithmic behavior (BGE-base-en embeddings, cosine, 500-char overlapping windows), the 200K char cap with truncation flagging, and the inclusion of character offsets for verbatim verification. This is rich, non-obvious context that annotations don't 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 appropriately sized — one focused paragraph. It front-loads the core purpose, then efficiently packs usage context, pairing, algorithm, and edge-case handling into a few sentences. 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?

Despite no output schema, the description explains the return format (top-N passages with character offsets and similarity scores). It also covers the 200K truncation behavior and the practical use case. The tool is fully contextualized for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond schema: it explains that 'text' should be a previously fetched record, gives example queries, and explains the 'top-N' behavior tied to limit. This elevates the parameter guidance above the schema alone.

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

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

The description opens with a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes the tool from siblings by framing it as a post-fetch, passage-level retrieval tool, and explicitly pairs it with ask_pipeworx_grounded to explain its unique role in the workflow.

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

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

Explicit guidance is given: 'Use when the record is too big to cram into the prompt' and 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This makes the intended usage and relationship to alternatives crystal clear.

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

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

The description adds substantial behavioral context beyond the annotations: it explains OAuth requirements, SMS phone verification and the 10/day cap, webhook signing secret issuance, and auto-disabling after 10 consecutive failures. These details are not present in the annotations and significantly improve understanding of side effects and constraints.

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 and every sentence carries information, but it is a dense block of text covering multiple types and deliveries. Given the tool's complexity, it remains efficient, though the length prevents a perfect score.

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 nested objects and no output schema, the description is remarkably complete: it covers all supported types, parameter shapes, delivery channels, authentication requirements, return value, and operational details like SMS caps and webhook signing. No significant gaps were found.

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

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

Schema coverage is 100%, so the baseline is 3, but the description enriches parameters with concrete examples, such as items:["5.02"] = officer change and params:{topic:"fed"}. It also adds critical caveats for delivery parameters (phone must be verified, webhook secret returned only once) that are absent from the schema descriptions.

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

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

The description clearly states the tool's action: 'Create a proactive monitoring subscription to a live-data event stream.' It also specifies the primary return value ('Returns the new subscription id') and enumerates supported types, making it distinct from siblings like list_subscriptions, unsubscribe, and recent_alerts.

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, including a prerequisite ('Requires a Pipeworx OAuth account') and an exclusion ('anonymous + BYO cannot persist subscriptions'). It also details delivery options and highlights the always-on feed, suggesting how to consume alerts. However, it does not explicitly compare against alternative tools like recent_alerts for one-off reads, so it falls short of 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 disclose read-only, idempotent, and non-destructive behavior. The description adds meaningful context: returns categorized examples drawn from the live catalog, and that omitting topic gives the full spread while passing topic focuses. It doesn't mention pagination or response size, but for this tool the added behavioral detail is solid.

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?

Despite being a dense paragraph, it's front-loaded with the purpose, then usage, parameter behavior, and when-to-use guidance. Every sentence adds value and there is no fluff or repetition.

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 one optional parameter and no output schema, the description fully covers what the tool does, what it returns, how to call it, and when to use it. It is self-sufficient for agent 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?

The schema covers topic with a description and allowed values (100% coverage). The description reinforces this and explains the semantic difference between omitting vs providing topic (full spread vs focused), with concrete examples like 'finance', 'pharma', 'betting', going 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 is the onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It clearly distinguishes from siblings by saying 'Use this FIRST' and naming meta-tools it helps you learn.

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

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

It gives explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also explains how to use the optional topic parameter to focus, and references alternatives like ask_pipeworx and entity_profile.

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 (mutation, idempotent, non-destructive), the description adds concrete behavioral details: ownership enforcement, deactivation rather than deletion, and the impact on recent_alerts. These details are not present in annotations and greatly improve the agent's understanding of the tool's side effects.

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, with the action front-loaded and the key behavioral nuance in the second sentence. Every word earns its place with no fluff or repetition.

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-parameter mutation tool with annotations and no output schema, the description is fully sufficient: it covers the action, ownership constraint, lifecycle consequence, and points to a related tool. Missing explicit error handling is acceptable given the tool's simplicity.

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

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

The input schema fully documents the single parameter (subscription id returned by subscribe), and the description adds no further parameter-specific details. This meets the baseline for high schema coverage, but the description does not elevate parameter 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 uses a specific verb and resource ('Cancel a subscription by id') and clearly distinguishes from siblings by noting ownership enforcement and deactivation rather than deletion. This makes its purpose unambiguous and differentiates it from subscribe, list_subscriptions, and recent_alerts.

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 when to use it: to cancel a subscription while preserving historical events via recent_alerts. It also notes the ownership restriction, but it does not explicitly state when not to use it or name alternatives, so it falls short of fully explicit guidance.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds crucial context beyond annotations: the could_not_verify verdict means the check did not happen and must not be treated as evidence, unsupported means no source exists, and the dual-path architecture (structured SEC EDGAR vs. grounded fallback) is revealed. This is exactly the kind of behavior an agent needs to know.

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 a minimal two-sentence summary but every section serves a purpose: query examples, purpose, routing, return values, and the critical could_not_verify caveat. It is appropriately front-loaded. Some redundancy exists between 'natural-language claim verification' and 'check whether...' but it remains efficient.

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

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

Since there is no output schema, the description fully compensates by enumerating the verdict values, mentioning the pipeworx:// citation and reasoning fields, and explaining the two failure modes (could_not_verify vs. unsupported). It also covers the internal processing paths and the tolerance semantics. This is complete for a tool with 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% coverage; both "claim" and "tolerance_pct" have detailed descriptions, with tolerance_pct explaining default behavior and hallucination-detection usage. The description adds no new parameter-level semantics beyond what the schema already provides, 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 opens with concrete natural-language query forms ("Is it true that…", "fact check"), then states the core function: natural-language claim verification against authoritative sources. It clearly differentiates from sibling tools by being a one-shot claim verifier with an explicit verdict enum, and even notes it replaces 4–6 sequential calls.

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 an explicit trigger: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains internal routing (financial vs. non-financial claims). However, it does not name alternative tools or explicitly state when not to use it, so it misses the full 'alternatives' bar.

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