Mojang

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds useful behavioral context beyond that: default model (Workers AI Llama-3.3-70b free), cost implication of using Anthropic ('BYO key — you pay Anthropic directly'), and return structure (per-model {score, confidence, signals, raw_response} + combined view). No contradiction with annotations.

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

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

The description is four sentences with zero filler. It front-loads the primary action, then efficiently covers defaults, return format, and use cases. Every sentence adds value.

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

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

For a 4-parameter tool with no output schema, the description communicates behavior, defaults, cost, return structure, and use cases. Gaps like scoring methodology or 'signals' details are not essential for selection/invocation. The description is complete enough for an agent to act.

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

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

Input schema covers all 4 parameters with descriptions (100% coverage), so the schema does the heavy lifting. The description adds one extra detail: the default model is Workers AI Llama-3.3-70b (free), and clarifies that passing _apiKey also probes Anthropic. This is useful but marginal; baseline of 3 is appropriate.

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

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

The description clearly states the tool's core function: 'Probe one or more LLMs for what they know... score visibility (0-100) per model.' It uses a specific verb and resource, and distinguishes itself from sibling tools like ask_pipeworx by focusing on visibility scoring rather than answering a question. Concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') reinforce purpose.

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

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

The description provides explicit use cases, implying when to use it ('Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring'). However, it does not name alternative tools or offer 'when not to use' guidance, 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 indicate read-only, idempotent, open-world, non-destructive. The description adds valuable context beyond annotations: routing across thousands of sources, argument filling, stable citation URIs, 'works on every tier', and 'one fast call'. No contradiction with annotations.

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

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

The description is long but every sentence earns its place: preference statement, what it does, when to use, examples, and alternatives. It is front-loaded with 'PREFER OVER WEB SEARCH' and uses clear separators. For a central router this length is justified and well-organized.

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 (routing to thousands of sources), minimal input schema, and no output schema, the description covers what is returned (structured answer with citations), performance characteristics, coverage, and when to use alternatives. It is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100% for all 6 parameters, but 5 are aliases for the single 'question' parameter. The description does not add new meaning beyond the schema's 'Your question or request in natural language' and examples. Baseline 3 is appropriate since the schema does the heavy lifting and the parameter is straightforward.

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 routes questions to one of 5,564 tools across 1,462 sources and returns structured answers with citation URIs. It goes beyond a simple verb+resource by explaining the routing mechanism, and explicitly distinguishes itself from ask_pipeworx_grounded and deep_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?

Provides explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE for most questions'), includes trigger phrases and examples, and names alternatives for when to step up (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for multi-part broad questions). Also clarifies that breaking-news queries are handled by this tool already.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: beta status, live candidate improvements, current absence of an active candidate, and that it is a full working router. This goes beyond annotations without contradicting them.

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

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

Description is compact but information-dense. Every sentence adds value: explaining equivalence, current state, and usage. Front-loaded with 'Beta version of ask_pipeworx' and avoids redundancy.

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

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

Given the tool's complexity as a universal router with no output schema, the description sufficiently covers purpose, current behavior, and usage. It could provide more detail about output formats, but since it states the response shape is identical to ask_pipeworx, it relies on that sibling for full context. Overall adequate.

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

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

Schema covers 100% of parameters, all being aliases for 'question'. The description adds no additional parameter semantics. Baseline of 3 is appropriate since the schema fully documents the parameter and the description does not need to compensate.

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

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

Description clearly identifies the tool as a beta version of ask_pipeworx, a universal router, and distinguishes it from the stable sibling by mentioning experimental routing improvements. It specifies the same toolset, arguments, and response shape, making the purpose precise and differentiated.

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

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

Provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It contrasts with the stable router and states that results are compared to decide merges. This gives a clear when-to-use and implies the alternative (ask_pipeworx) for stable needs.

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

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

Annotations already state readOnly/opendWorld/idempotent, but description adds value by detailing refusal behavior (returns refusal_reason with specific enum values) and the extra LLM call cost. This goes beyond annotations without contradicting them.

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

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

Description is dense but well-structured: purpose first, then return format, then usage guidance. Slightly long but each sentence contributes distinctive value. No fluff.

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

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

Without an output schema, the description fully explains the return envelope including success and refusal cases. Covers cost, use cases, and relationship to sibling. Complete for a complex 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 each parameter documented as an alias for 'question.' Description does not add parameter-specific semantics, only generically says it 'fills arguments' for other tools. Baseline 3 applies since schema does the heavy lifting.

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 defines tool as a hallucination-resistant answer mode for high-stakes reads, explicitly differentiates from sibling ask_pipeworx by emphasizing extraction only from tool results and evidence return. Uses specific verb 'extracts' and resource 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 when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on,' and explicit when-not-to: 'prefer ask_pipeworx for casual lookups.' Also mentions the extra LLM call cost as a trade-off, which helps decision-making.

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), the description discloses extensive behavioral details: resolver confidence levels, safety short-circuiting for low-confidence matches, closed-market status handling, wide-spread liquidity flags, news fallback behavior, and resolution-rule risk parsing. It adds critical context about potential pitfalls (e.g., flat-50¢ void settlements) that annotations cannot convey.

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

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

The description is long but exceptionally dense, using clear section headers (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) to organize content. Every sentence adds unique value—no filler or redundancy. While it could be tightened, the complexity of the tool justifies the length, and the front-loaded purpose and usage lines make it scannable.

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

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

Despite having no output schema, the description fully documents result shapes, edge cases, failure modes, and resolution rules. It covers resolver confidence, parent-event extraction, news fallbacks, tradeability warnings, and cancellation-rule parsing—far exceeding what is typically provided. The tool's complexity is matched by a remarkably complete description.

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

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

Schema coverage is 100% and each parameter already has a detailed description (e.g., market accepts slug/URL/question text, depth enum, include_raw summary vs full payloads). The description adds some real-world context (e.g., recommended defaults, fan-out examples) but does not materially enhance parameter semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly delineates the tool's function, including input forms (slug, URL, question text) and the output (evidence packet + market-vs-model comparison). It also distinguishes itself from siblings by focusing on Polymarket bet research with category-specific fan-out.

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

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

The description provides explicit use cases ('Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"') and advises when to inspect resolver fields and cancellation rules. However, it does not name alternative sibling tools or give 'when-not-to-use' exclusions, 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, and destructiveHint=false, so the safety profile is known. The description adds valuable context beyond annotations by specifying the return structure ('count and hashes array') and the data source ('Session Server'). No contradictions with annotations.

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

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

The description is a single, well-structured sentence that immediately states the verb and resource, then adds output details. Every word earns its place, with no unnecessary filler or repetition of schema data.

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 zero-parameter tool with an output schema present, the description completely covers the essential information: what is retrieved, in what format, and from where. There are no gaps in context, and the included output schema handles return value details.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter meanings. It correctly implies the operation requires no input by specifying the retrieval action.

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 ('Retrieve'), a precise resource ('Mojang's blocklist of banned Minecraft multiplayer servers'), and the output format ('SHA-1 hashes; returns count and hashes array'). It is easily distinguishable from all sibling tools, as none others deal with server blocklists.

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 this tool: when needing Mojang's blocklist of banned Minecraft servers. There are no explicit exclusions or alternative recommendations, but given the tool's unique purpose among siblings, this is sufficient. A slight deduction for not explicitly stating 'use when you need the blocklist' or naming 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?

The description goes well beyond the read-only/idempotent annotations, detailing data sources (SEC EDGAR/XBRL, FAERS), specific metrics pulled (revenue, net income, adverse-event counts), sorting behavior by primary metric, and output format (paired data + citation URIs). No contradiction with annotations.

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

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

The description is dense but well-structured, front-loaded with trigger phrases and clear sections. Minor redundancy: the sequential-lookup savings is mentioned twice ('ALWAYS PREFER...' and 'Replaces 8–15...'), but otherwise every sentence serves a 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 description fully covers the tool's purpose, usage, data behavior, and output format. With annotations providing safety (read-only, idempotent, non-destructive) and an output schema absent, the description compensates by describing return values and sorting. It is complete for an agent to decide when and how to invoke it.

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

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

Although schema coverage is 100%, the description enriches parameter meaning significantly. It explains that type='company' pulls specific financial data and type='drug' pulls FAERS/FDA/trial data, and clarifies values format ('tickers/CIKs' vs 'drug names') with examples, which is beyond the schema's basic enum/array 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 states exactly what the tool does: side-by-side comparison of 2–5 companies or drugs in one parallel call. It uses specific verbs ('compare', 'rank') and gives trigger phrases like 'X vs Y', clearly distinguishing it from a single-entity lookup tool.

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

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

Explicitly instructs when to use: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and mentions it 'Replaces 8–15 sequential lookups.' This clearly differentiates it from tools like entity_profile for single lookups, and provides use cases for both company and drug types.

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 provide readOnly/openWorld/idempotent hints, and the description adds substantial behavioral context: account/paid-tier requirements, 'NOT open-web search', parallel routing to 5,564 tools, never-invented gaps[], contradictions[] on standard/thorough, semantic excerpting, latency expectations, and resolvable citation behavior. 'Not open-web search' narrows external access rather than contradicting openWorldHint, since the tool still accesses external structured sources.

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

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

The description is dense and front-loaded with critical account and fallback information. It is long, but nearly every sentence carries actionable detail for a complex tool; minor redundancy exists in repeating ask_pipeworx alternatives, so it is not maximally concise.

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

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

Even without an output schema, the description specifies the full shape of the return: findings packet with evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], hop, and citation_uri. It also covers latency, prerequisites, and failure behavior, making it complete for agent decision-making.

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

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

Schema coverage is 100% and the schema already documents both parameters, but the description adds meaning beyond the schema: depth is explained in terms of facet counts, hop behavior, paid tier, and contradiction scans, while question is clarified as a natural-language broad/multi-part query appropriate for decomposition.

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

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

The description clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' and returns a findings packet. It uses a specific verb-plus-resource formulation and explicitly distinguishes itself from ask_pipeworx, making its scope unambiguous among siblings.

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

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

It gives explicit when-to-use guidance: broad/multi-part questions over structured data. It also states when not to use it: single lookups, breaking news, colloquial current-news topics, and signed-out users, naming ask_pipeworx as the alternative. Depth selection guidance (standard vs thorough) further clarifies trade-offs.

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, so the safety profile is covered. The description adds useful behavioral context about the output: it returns top-N tools with names, descriptions, full input schemas, and curated examples, ready to call directly with no second lookup. This goes beyond the annotations and clarifies the interaction 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 four sentences and front-loaded with the core purpose. Each sentence has a distinct role: purpose, usage context, output behavior, and when-to-call guidance. The lengthy domain list is somewhat dense but serves as concrete examples of intended queries, so it earns its place. It is slightly longer than necessary, preventing 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?

The tool is a discovery meta-tool with no output schema, but the description fully explains what the return value looks like: top-N tools with names, descriptions, full schemas, and curated examples, ready for direct invocation. It also covers when to use it and the kinds of tasks it supports. Given the tool's complexity and the rich schema, the description is complete enough for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, and the schema thoroughly documents all six parameters including aliases and the limit parameter with defaults. The description adds general guidance about natural-language queries and the result set, but it does not meaningfully improve parameter-level understanding beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description uses a specific verb+resource pair: 'Find tools by describing the data or task.' It clearly distinguishes this tool as a meta-discovery tool for browsing the available option set, unlike the many domain-specific sibling tools. The list of supported domains further clarifies its scope.

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

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

The description explicitly states when to use it: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It gives clear context and an implied exclusion ('not just one answer'), but it does not explicitly name alternative tools or state when not to use it, so it falls just 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 declare this as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it fans out across multiple sources (SEC, XBRL, USPTO, GDELT, GLEIF), returns specific fields, soft-fails for patents due to API sunset, and specifies the return format (CIK, filings with URIs, fundamentals). This is rich, non-redundant disclosure 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 a single well-organized paragraph, front-loaded with example queries to quickly establish intent. Every sentence adds value: usage triggers, preference over alternatives, data sources, return fields, parameter constraints, and API sunset behavior. It is dense but not bloated.

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

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

Given the tool's complexity (multi-source aggregation), the absence of an output schema, and the presence of only basic annotations, the description is remarkably complete. It details what data is returned, how failures are handled (soft-fail for patents), and prerequisites (ticker/CIK vs name). 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 input schema already provides 100% coverage of both parameters, including the enum for type and the exact accepted values for value (ticker or zero-padded CIK, names not supported). The description repeats this information but does not add new conceptual meaning beyond the schema descriptions. It reinforces the guidance but does not extend 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 clearly states the tool's purpose: to provide a full cross-source profile of a US public company in one parallel call. It includes specific examples of user queries and explicitly distinguishes itself from sibling tools by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news 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?

The description gives explicit guidance on when to use the tool (when a holistic view is requested) and when not to (when only a name is provided, use resolve_entity first). It also mentions preference over chaining other lookups, providing clear decision criteria.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's 'Delete' adds no new behavioral information. It mentions clearing sensitive data as a use case, but this is more motivational than behavioral. No contradiction with annotations.

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

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

Two concise sentences: the first states the action, the second gives usage context and related tools. No wasted words; front-loaded with the primary 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?

For a simple one-parameter deletion tool with no output schema, this description is complete. It explains purpose, when to use, and pairs with other memory tools, while annotations cover safety traits.

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

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

Schema covers the single parameter 'key' with a clear description ('Memory key to delete') and 100% coverage. The tool description does not add any additional meaning about key format or edge cases, so it stays at the baseline of 3.

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

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

The description states 'Delete a previously stored memory by key' with a specific verb and resource, clearly distinguishing it from sibling tools remember and recall. It unambiguously defines the tool's function.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also names companion tools 'Pair with remember and recall', providing clear usage guidance and alternatives.

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

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

The description discloses that it fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format. This goes beyond the readOnlyHint annotation by explaining the processing steps, adding useful behavioral context 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 three sentences, front-loaded with the purpose, and every sentence adds value. It is concise and well-structured with no redundant information.

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

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

Given the simple tool (2 params, no output schema), the description fully covers behavior, output format, and use cases. It mentions the output is a text blob ready to place at site-root/llms.txt, which is sufficient for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds minor context (e.g., 'key links' relates to max_links) but doesn't significantly enhance parameter understanding 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 generates a production-ready llms.txt file for any URL, specifying the output format and target use cases (AI crawlers). This is a specific verb+resource with a clear scope, distinguishing it from related tools.

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

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

The description provides explicit use cases (e.g., getting a client's site indexed, drafting llms.txt for a project, auditing competitor visibility), giving clear context for when to use it. It doesn't explicitly mention alternatives or exclusions, so it's a 4 rather than 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 and destructiveHint=false, so the agent knows it's a safe read. The description adds value by disclosing the default behavior (active only) and the returned fields (id, type, params, timestamps, fire_count), which 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 two sentences, front-loaded with the action, and includes both return fields and usage guidance. Every sentence earns its place with no redundancy.

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

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

For a simple list tool with one optional parameter and no output schema, the description is complete: it states the purpose, default behavior, returned fields, and practical use cases. No critical information appears 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% with the single parameter 'include_inactive' fully described. The description does not add additional parameter semantics beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It differentiates from sibling tools like subscribe and unsubscribe by focusing on listing, and the return fields are specified.

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: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives clear context for when to use the tool, though it does not explicitly mention alternatives or exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds that it returns a list of past usernames and timestamps, which is return-value context rather than behavioral nuance. It does not disclose potential errors, rate limits, or prerequisites beyond 'by UUID'.

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 one sentence with no filler words. It front-loads the action ('Fetch'), states the resource, input, and output summary in a compact manner. Every word contributes to understanding.

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 a single parameter, an output schema, and a read-only operation, the description fully explains the tool's purpose and expected return without needing additional context. It is complete for the tool's complexity.

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

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

Schema description coverage is 0%, so the description must compensate for the uuid parameter. The phrase 'by UUID' clarifies that the uuid parameter is the Minecraft account UUID, adding essential meaning beyond the raw schema. It does not specify format (e.g., dashed vs. undashed), but for a single parameter, this is sufficient.

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 'Fetch' and identifies the resource as the full name-change history for a Minecraft account, filtered by UUID. It clearly differentiates from sibling tools like username_to_uuid which map usernames to UUIDs, and username_to_uuid_at which look up UUIDs at a specific time.

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 that this tool is for retrieving name-change history, implying its use case without ambiguity. It does not explicitly mention alternatives or when-not-to-use, but the scope is so specific that an agent can infer the appropriate usage. There are no exclusions stated.

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 (which are all false and minimally informative), the description discloses rate limits ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and the claim-token mechanism ('Filing without an account returns a claim_token; pass it back later... to read whether it was fixed'). The team's daily digest and roadmap influence are also contextual behavioral traits. This adds substantial value beyond annotations.

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

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

The description is about six sentences long, but every sentence earns its place: purpose, when to use, exclusion, message guidelines, claim-token process, rate limit/cost, and team impact. It is front-loaded with the core verb and immediately gives the categories. There is no fluff or redundancy; each sentence conveys distinct, actionable information.

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

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

Given the tool has no output schema and has nested parameters, the description is complete. It explains the response (claim_token), how to check status later, rate limiting, cost, and the constraint to describe issues in terms of Pipeworx tools. It also clarifies what not to include (end-user prompt). No critical context is missing for an agent to invoke this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra semantic guidance beyond the schema, notably 'don't paste the end-user's prompt' for the message parameter and a concrete invocation example for claim_token: 'pipeworx_feedback({claim_token:"pwfb_…"})'. It also reinforces that context should refer to Pipeworx tools/packs, which clarifies the context object's purpose.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb and resource, and the phrase 'broken, missing, or needs to exist' maps to bug/feature/data_gap categories. It is distinct from all sibling tools, which focus on research, visibility, or subscriptions, so there is no confusion.

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

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

The description explicitly states when to use the tool: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a strong exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' This is clear when/when-not guidance with an alternative action.

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), the description adds valuable context: it is self-aggregating, derived from the CF analytics-engine, contains no PII, and is cached 5min-1h depending on window. These details disclose data sources and freshness behavior, exceeding what annotations alone 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 concise, front-loaded with the purpose, then practical use cases, then technical details. Every sentence contributes meaning—no filler, no redundant restatement of the name or 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?

Although there is no output schema, the description specifies the return contents ('top tools, top packs, total call volume', 'just (pack, tool, count)'), the windows, caching behavior, and privacy. This is sufficient for an agent to understand what it will receive. Minor lack of exact response structure, but not critical for a simple aggregator.

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

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

Schema coverage is 100%, and the description additionally explains the practical difference between windows: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enriches the enum parameter with decision guidance, going beyond the schema's basic definitions.

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

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

The description clearly states the tool returns trending usage data ('top tools, top packs, and total call volume') over a recent window, with the core phrase 'What other AI agents are calling on Pipeworx right now.' This specific verb+resource combination distinguishes it from sibling tools like discover_tools, which likely lists available tools rather than current usage trends.

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 offers explicit use cases ('Useful for: discovering hot data sources, confirming canonical tools, aligning with agent needs'), providing clear context for when to use the tool. However, it does not explicitly mention when not to use it or name alternative sibling tools, so it stops short of full 'when/when-not/alternatives' guidance.

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

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

The description goes beyond the readOnly/idempotent annotations by detailing the fill check behavior, the condition where realizable_edge_pp <= 0 means the opportunity is not tradable, and the partition filter logic. These behaviors are not otherwise disclosed by annotations.

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

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

The description is long but each sentence adds unique value and follows a logical structure: summary, mode explanations, semantic anchor, partition filter, response format, fill check. It is front-loaded with the core purpose and then details, with no redundant 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 no output schema, but the description fully documents the response structure (opportunities[] fields, partition_check subfields) and explains edge-case behavior like null signals and fill pricing. Given the tool's complexity, this level of detail is necessary and 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 schema coverage is 100%, the description enriches parameter meaning with concrete examples (e.g., event slug 'fed-decision-may-2026', topic 'Strait of Hormuz traffic returns to normal') and explains the behavioral differences between event and topic modes beyond simple property descriptions.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between the three invocation modes (no args, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit usage guidance is provided for each mode, including when to use event vs topic vs trending_scan. It also references an alternative tool (polymarket_fill_risk) for custom sizing, making exclusion criteria clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds substantial context: model families, edge metrics, the 24h-move warning, caching ('Cached 1h at the KV level'), and diagnostics structure. It also explains subtle behavior like partition arbs always returning kelly_fraction_half=0 by design. No contradiction with annotations.

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

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

The description is long but well-structured with uppercase section callouts for model families, knobs, response top-level, and caching. It front-loads the core purpose. Some details (specific sport alphas, gate relaxation history) are arguably over-specified, but for a complex tool they provide useful behavioral insight. No fluff, though length could be trimmed.

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 9 parameters and no output schema, the tool is complex. The description thoroughly covers the response shape: top-level by_segment, fed_candidates/fed_note, _diagnostics; per-opportunity fields like edge_pp_net, kelly_fraction, market.liquidity, spread_pp, volume; and the 24h-move warning. It also explains knobs and caching, making it complete enough for an agent to invoke and interpret results.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning by framing min_liquidity and max_spread_pp as 'TRADEABLE-EDGE KNOBS' and clarifying min_partition_leg_kelly's interaction with partition arbs, which the schema does not fully explain. This elevates the semantics beyond the simple parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes itself from siblings by focusing on Pipeworx data disagreements and the 'what should I bet on today' use case. The enumeration of model families and response segments makes the purpose unmistakable.

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

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

Clear context is provided: 'Built for "what should I bet on today"' and 'without paging hundreds of markets.' It also notes that Fed bets are excluded from ranking due to unreliability. However, it does not explicitly name alternative tools or state when not to use this tool in favor of siblings like polymarket_arbitrage or polymarket_edge_tracker, so it lacks explicit exclusions.

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

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

The description adds substantial behavioral context beyond the annotations: it explains snapshot write timing ('snapshots are written when polymarket_edges runs on a cache-miss, so gaps mean nobody scanned that day'), history depth limits ('bounded by the 60-day snapshot TTL'), and calculation nuances ('decay numbers come from daily closes of edge_pp_net (net of default slippage), not intraday'). It also details the response structure, including the sign convention for edge_pp_net.

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

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

The description is well-structured with clear sections (introduction, Args, RESPONSE, LIMITS) and every sentence carries useful information. It is longer than average, but given the tool's complexity (time-series analysis, response fields, limitations), the length is justified and the organization aids comprehension.

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

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

With no output schema, the description fully specifies the response structure (tracked[], expired[], snapshot_dates[]) including field-level semantics (e.g., edge_pp_net time-series, first_seen, trend, decay_pp_per_day, lifespan_days). It also covers limitations and data availability nuances, making the description complete for an agent to understand the tool's behavior and return values.

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

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

The input schema already provides 100% coverage for both parameters (days and window) with descriptions. The description repeats the parameter info ('days (lookback, default 14, max 30), window (snapshot family, default "1wk")') and adds the phrase 'snapshot family' but does not significantly enrich beyond what the schema provides. Hence 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 the tool's purpose as 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers the specific question 'how long has this edge existed and is it shrinking?'. It distinguishes itself from the sibling tool polymarket_edges by focusing on historical persistence and decay rather than current edge values.

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 by contrasting fresh vs. old edges ('a fresh wide edge and a 3-week-old wide edge are different trades'), implying this tool is for assessing edge age and decay. However, it does not explicitly name alternatives or state when not to use it, so it lacks explicit exclusionary guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavioral detail beyond these: it walks the order book, returns specific fields like vwap_fill_price, slippage_pp, and verdict, and discloses risks such as thin_legs[] and forced_directional_risk. No contradiction with annotations.

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

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

The description is long but well-organized with clear SINGLE-MARKET and BASKET sections. It front-loads the core purpose and then delivers necessary details in a structured way. Every sentence contributes value, and there is no filler or redundancy.

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

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

Given the tool's complexity (two modes, 4 parameters, no output schema), the description is remarkably complete. It enumerates expected outputs (top_of_book, capture_ratio, profit_usd, per-leg fill detail, etc.), covers failure modes, and explains the verdict categories, leaving no critical gaps for an agent deciding to invoke it.

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

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

While the schema covers 100% of parameters, the description adds meaning beyond the brief schema descriptions. It explains that market and event are mutually exclusive modes, clarifies how size_usd is interpreted differently in each mode (max spend/proceeds vs settlement notional), and mentions defaults and clamps. This is significant added semantics.

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

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

The description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth', a specific verb+resource that clearly defines the tool's function. It further distinguishes itself from sibling tools by explicitly naming polymarket_arbitrage and polymarket_edges and positioning this tool as the pre-trade risk check.

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 direction: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the rationale, warning that theoretical overround on thin books is not capturable and partial basket fills create unhedged directional risk, which clearly guides when to use the 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?

The description richly discloses behavior beyond annotations: it explains compatibility_warning conditions, temporal_alignment, skipped_cross_type semantics, and the meaning of matched_pairs=0 scenarios. This adds substantial context beyond the readOnly/openWorld/idempotent hints.

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 clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. Every sentence adds useful information, though it is denser than needed for a simple tool, justifying a 4 rather than 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?

For a tool with zero required params and no output schema, the description is exceptionally complete: it covers modes, response format, safety fields, temporal alignment, and real-world caveats. It fully equips the agent to understand when and how to invoke 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%, so the baseline is 3. The description adds mode semantics by explaining how topic shortcuts work and how explicit kalshi_event_ticker and polymarket_event_slug override the mapped sides, providing meaningful context beyond the schema.

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

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

The description clearly identifies a cross-venue spread between Kalshi and Polymarket for the same resolving question, which is a specific verb+resource. However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edges, so it lacks explicit sibling differentiation.

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

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

The description provides clear context on usage with two modes (topic shortcuts and explicit tickers) and warns that most pre-mapped topics return compatibility_warning, implying when results are meaningful. It does not explicitly mention alternatives or exclusions, 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, idempotentHint, and destructiveHint, covering safety. The description adds context that the data comes from an external Mojang Session Server and that the profile is public, which is marginally useful. However, it does not discuss rate limits, failure modes, or other behavioral quirks, so it adds only limited value beyond annotations.

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

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

The description is a single, front-loaded sentence that gets straight to the action ('Fetch'), specifies the resource and input, and notes the output. Every word earns its place with 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?

Given the tool's simplicity (one parameter, no nested objects) and the presence of an output schema, the description covers the essential aspects: purpose, input semantics, data source, and return type. It is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 0% because the uuid property has no description. The tool description compensates by stating that the parameter is a Minecraft player's UUID, directly linking it to the 'Fetch by UUID' behavior. This adds meaningful semantics beyond the bare 'string' type in the schema.

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

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

The description uses a specific verb 'Fetch' and identifies a precise resource: 'a Minecraft player's public profile by UUID via Mojang Session Server'. It also states the return value ('current username and skin/cape texture URLs'), which clearly distinguishes it from sibling tools like username_to_uuid or name_history.

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 clearly implies the use case: when you have a UUID and want the current public profile of a Minecraft player. It does not explicitly name alternatives or exclusions, but the context is clear enough to guide an agent. Sibling tools such as username_to_uuid serve a different purpose, so the tool's role is unambiguous.

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 value beyond these by disclosing the key-listing behavior when the key is omitted and the scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID).

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, and every sentence earns its place — 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?

For a simple one-parameter tool with no output schema and strong annotations, the description covers purpose, usage, scoping, and complementary tools. It is complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100% and the schema description already explains the key parameter and the omit-to-list-all behavior. The description adds minimal extra semantics, only reinforcing the relationship to remember, so baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves a previously saved value via remember or lists all saved keys when the key argument is omitted. It uses specific verbs and resource ('retrieve a value', 'list all saved keys'), and distinguishes itself from sibling tools 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?

It explicitly says to use this tool to look up context the agent stored earlier without re-deriving it, and pairs it with siblings: 'Pair with remember to save, forget to delete.' This provides clear when-to-use and alternatives.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses the mark_read side effect ('flag returned events read so the next call only shows newer ones'), the return payload structure (source, citation_uri, raw event payload), and that the same feed is available via a public endpoint. No contradictions with annotations.

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

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

Three compact sentences front-load the core purpose, then add filtering/mark_read semantics, and finally polling guidance and an alternative access point. Every sentence contributes new information without redundancy.

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

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

Even without an output schema, the description covers the return format (source, citation_uri, raw payload), filtering options, side effects, and polling behavior. This is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds meaningful examples ('sec_8k' for type), clarifies since as ISO timestamp, and explains the functional consequence of mark_read. It does not mention limit or unread_only, but those are adequately described in the schema.

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

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

The description opens with 'Pull fired events from your subscription feed' — a specific verb and resource. It clearly distinguishes this from siblings like list_subscriptions, subscribe, and recent_changes by focusing on reading alert events from the persisted 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?

Provides clear context: mentions filtering by type and since, using mark_read to advance the feed, and that 'Polls work fine.' It also offers an alternative access mechanism (registry.pipeworx.io/alerts.json). However, it does not explicitly name a sibling tool as an alternative or state when not to use this tool.

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

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

Beyond the read-only/idempotent annotations, the description reveals the multi-source fan-out, GDELT→GNews fallback for rate limits/5xx, and the USPTO PatentsView soft-failure after May 2025. It also clarifies the return shape including citation URIs, which is not visible in any structured field.

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

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

The description is dense and information-rich, covering query examples, sources, fallbacks, date formats, return shape, and an alternative in one paragraph. While all content is necessary, the lack of bullet points or segmentation slightly reduces scannability.

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

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

For a tool with no output schema, the description explains return structure (changes[], total_changes, citation URIs) and edge cases (patent soft-fail). It also addresses multi-source complexity and gives an alternative, making it sufficiently complete for agent use.

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

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

The schema already documents all three parameters, so the baseline is 3. The description adds value by explaining accepted forms for `since` (ISO or relative) and recommending '30d'/'1m' for typical monitoring, going beyond schema definitions.

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

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

The description clearly identifies the tool as a change feed for companies, listing example queries and the underlying data sources. It explicitly contrasts with entity_profile, distinguishing its dynamic window-based scope from a static 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?

It provides explicit guidance by showing natural-language triggers ('What's new with X') and specifying when to choose entity_profile instead. It also explains fallback logic and relative date syntax, equipping the agent to decide when this tool fits.

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

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

Adds valuable behavioral context beyond annotations: persistence scoped to identifier, 24-hour retention for anonymous sessions, and key-value pairing. No contradictions with annotations (idempotent, non-destructive). The only missing detail is explicit overwrite behavior, but idempotentHint already covers that.

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

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

Four sentences, each earning its place: purpose, usage, storage mechanics, and companion tools. No filler or redundancy; front-loaded with the core action.

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 two-parameter tool with no output schema and comprehensive annotations, the description covers all essential aspects: purpose, when to use, persistence, scoping, and relationships to sibling tools. 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 covers 100% of parameters with clear descriptions, so the description adds little beyond that. It reinforces key-value semantics with examples, but these largely mirror the schema's own examples, providing no significant additional 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 the tool saves data for later reuse with specific verb ('Save') and resource ('data'), and distinguishes it from siblings by explicitly pairing with recall and forget. Examples of what to store (resolved ticker, target address) make the purpose unmistakable.

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

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

Provides explicit 'Use when' guidance with concrete scenarios, and names alternatives (recall, forget) with their roles. This gives clear direction on when to invoke this tool versus other memory-related tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, so safety and idempotence are clear. The description adds value by detailing cascading internal lookups (SEC, GLEIF, OpenFIGI, RxNorm), graceful degradation of LEI/FIGI, and the `unresolved` field behavior – rich behavioral context beyond annotations.

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

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

The description is front-loaded with example queries and usage guidance, which is good. However, it is quite long and includes some redundancy (e.g., listing each identifier for company twice). Some sentences are dense and could be trimmed without losing meaning.

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

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

For a tool with 100% schema coverage and no output schema, the description sufficiently explains inputs, resolution behavior, and edge cases (unresolved identifiers, degraded enrichment). The only gap is no mention of return structure beyond `unresolved`, but without an output schema, this is acceptable. Meets needs given complexity.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds value by explaining what each entity type resolves to (e.g., CIK+ticker+LEI for company), but the parameter syntax and input values are well-covered by the schema. Baseline 3 is appropriate.

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

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

The description explicitly states it resolves user-spoken names to canonical identifiers, listing examples and supported entity types (company, drug). It clearly distinguishes from siblings like compare_entities or entity_profile by focusing on identifier resolution rather than comparison or profiling.

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

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

The description gives explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID'), lists query patterns that trigger it, and covers graceful degradation when external services (GLEIF, OpenFIGI) are unavailable, helping the agent decide when to fall back.

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 readOnly/idempotent, and the description adds behavioral detail: it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It also specifies the return format (ranked list with score, confidence, signal density). No contradiction with annotations.

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

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

Three sentences, front-loaded with the primary action, then use case, then return details. Every sentence adds value without unnecessary 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?

Given the tool's complexity (multi-entity, options for models and API key), the description covers purpose, process, return value, and parameter semantics. The absence of an output schema is compensated by stating what the ranked list contains. No major gaps.

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

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

Schema coverage is 100%, and the description enriches the 'entities' parameter by explaining that the first entry is the 'subject' for narrative, with the rest as competitors. It also clarifies the 'context' parameter as a shared disambiguator. Models and _apiKey are sufficiently described in the schema.

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

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

The description clearly states it compares AI visibility across multiple entities, probes each with ai_visibility_check, and ranks results. This distinguishes it from the single-entity ai_visibility_check sibling and generic compare_entities, 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 frames when to use it ('useful for competitive AI-marketing audits') and implicitly contrasts with ai_visibility_check by showing it handles multiple entities. It could be improved by naming the alternative explicitly, but the context is strong.

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

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

The description goes well beyond annotations by disclosing service fan-out, partial failure behavior ('sources_failed will list it if it times out, the rest still returns'), timing caveats ('first measurement on a new version can take 5-30s'), and ecosystem limitations. Annotations already declare readOnly/idempotent, and the description reinforces with operational details.

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

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

The description is dense but well-organized: purpose first, then usage, then output, then caveats. Every sentence adds value, though it could be broken into shorter sentences for easier scanning. The front-loaded core purpose earns high marks.

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

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

Given no output schema, the description thoroughly covers return values (summary block fields, per-advisory links, alternative versions), failure modes, and performance caveats. It also addresses ecosystem boundaries and fallback routing, making it self-sufficient 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 the baseline is 3. The description does not add much beyond the schema: it mentions 'package' is an npm package name and 'version' defaults to latest, both already in the schema. No additional semantic depth is provided for parameters.

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

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

The description clearly states the tool's purpose with a specific verb phrase: 'Composite "should I add this npm package to my project" check in ONE call'. It identifies the resources (deps.dev and bundlephobia) and the output (summary block, advisories, links, alternative versions), making it distinct from any sibling tool.

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

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

Explicit usage conditions are provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also excludes non-NPM ecosystems ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), giving 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?

The description discloses several behavioral details beyond the annotations: it returns character offsets and similarity scores, uses specific embedding/window parameters, and truncates inputs above 200K chars with a flag. These details are not in the annotations (which only declare read-only/idempotent) and materially help the agent anticipate output and limitations.

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 ~120 words but appears front-loaded with the core function first, followed by use case, pairing, and technical details. No sentence is wasted, though it could be trimmed slightly. Given the density of useful content, it earns a 4 rather than 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?

For a tool without an output schema, the description explicitly states return format (top-N passages with offsets and similarity scores), algorithmic behavior (BGE-base-en, 500-char windows), and limits (200K cap with truncation flag). This covers all key aspects an agent needs to invoke it correctly, including integration with a sibling tool.

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

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

The input schema already covers all three parameters with descriptions (100% coverage), so the baseline is 3. The description adds context about what 'text' means (e.g., an SEC filing) and example queries, but it doesn't add new parameter-level information beyond the schema. The limit parameter's range is also present in the schema.

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

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

The description clearly states the tool performs semantic search inside a provided text blob, with a specific verb and resource. It distinguishes itself from siblings like ask_pipeworx_grounded by emphasizing it operates on already-fetched text, not on gateway queries.

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

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

It explicitly tells the agent when to use it ('when the record is too big to cram into the prompt'), explains the benefit (saves context, returns only relevant passages), and names a paired tool (ask_pipeworx_grounded) for grounding over selected passages. This exceeds a simple 'use for X' by providing a workflow.

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

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

The description adds behavioral context beyond the annotations: auth requirement, return of subscription id, SMS verification and 10/day cap, and always-on feed pullable via recent_alerts. It does not contradict the annotations. It omits webhook auto-disable and idempotency behavior, but those are partially covered by schema and annotations.

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

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

The description is dense but well-structured: purpose, auth requirement, type catalog, and delivery channels. Each sentence carries information, and the most important facts are front-loaded. No filler.

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

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

Given the tool's complexity (5 types, nested params object, delivery channels) and lack of output schema, the description covers the critical return value (subscription id), auth prerequisite, all major delivery channels, and edge constraints like SMS verification/cap. The webhook option is left to the schema, but the description is sufficiently complete for selection and correct invocation.

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

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

Schema description coverage is 100% and the schema's params already include type-specific filter shapes, delivery formats, and webhook constraints. The description reinforces with examples (items:['5.02'], topic:'fed', series_id:'UNRATE') but does not add meaning beyond the schema; 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 opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly distinguishes subscribe from siblings like list_subscriptions and unsubscribe by framing it as creation/registration rather than listing or canceling.

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 specifies prerequisites (Pipeworx OAuth account, anonymous/BYO cannot persist), enumerates supported subscription types, and explains delivery options, including when to use recent_alerts for the feed. It does not explicitly name alternative tools like unsubscribe or list_subscriptions, but the usage context is clearly delineated.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds that it returns example questions with tool+argument shapes from a live catalog, and that omitting topic gives a cross-category spread. It does not disclose any surprising behavior not already implied by annotations, so 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 longer than average but every sentence is informative: example queries, return content, parameter usage, and use-case guidance. It is front-loaded with purpose and structured logically. It could be tightened without losing value, but it is far from wasteful.

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

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

With no output schema, the description carries the burden of explaining what the tool returns, and it does: category-bucketed example questions with exact tool and argument shape. It also explains the optional parameter behavior and the catalog source. It does not detail output structure or mention any potential variability, but given the moderate complexity, it is largely 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 topic documented including allowed values, so the baseline is 3. The description adds value beyond the schema by explaining that omitting topic returns a full cross-category spread and that topic focuses results, giving practical semantics not present in the schema field description.

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

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

The description opens with example user queries and clearly states the tool's function: returning category-bucketed example questions with exact tool and argument shapes. It positions itself as the onboarding entry point and explicitly names meta-tools (ask_pipeworx, entity_profile) that it teaches how to call, distinguishing it from siblings like discover_tools and deep_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?

The description gives explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the optional topic parameter to focus results. However, it does not explicitly state when not to use it or compare with the similar discover_tools sibling, so it falls short of a 5.

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

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

The description discloses soft-delete behavior ('The row is deactivated (not deleted)') and its impact on historical events ('stay available via recent_alerts'), which goes beyond the annotations. It adds meaningful behavioral nuance the annotations don't capture.

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

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

Two sentences, front-loaded with the core purpose, followed by essential behavioral details. No unnecessary words or redundancy; every clause earns its place.

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

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

For a simple one-parameter tool, the description covers purpose, ownership constraint, side effects, and relationship to recent_alerts. With strong schema and annotations, nothing essential is missing.

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

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

The schema already fully describes the id parameter ('Subscription id (uuid) returned by subscribe'), so with 100% schema coverage, the description doesn't need to add parameter details. The description's 'by id' adds no new semantic value.

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

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

The description opens with 'Cancel a subscription by id', clearly stating the verb (cancel), resource (subscription), and method (by id). It also distinguishes the tool from siblings like subscribe and list_subscriptions while adding ownership context.

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

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

It provides clear context for use: ownership is enforced ('you can only cancel your own subscriptions') and deactivation semantics are explained. However, it doesn't explicitly mention alternatives or when-not-to-use scenarios beyond the ownership restriction, 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 read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral context by specifying the result is the 'current' and 'canonical' UUID string, which 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 a single, front-loaded sentence that immediately states the action and result. The second clause adds useful return semantics without unnecessary filler.

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

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

For a simple single-parameter read-only tool with an output schema, the description is largely complete. It omits edge cases like unknown usernames or case sensitivity, but given the low complexity and strong annotations, it is sufficient.

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

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

With a single 'username' parameter and 0% schema description coverage, the description only reiterates that it is a Minecraft username. It does not add format, case-sensitivity, or validation details, so it fails to compensate for the schema's lack of information.

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

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

The description uses a specific verb ('Resolve') with a clear resource ('Minecraft username') and result ('current Mojang UUID'), making the tool's purpose immediately obvious. The word 'current' differentiates it from sibling tools like username_to_uuid_at.

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

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

The description implies usage for resolving the current UUID, which provides clear context and distinguishes it from historical lookups. However, it does not explicitly name alternatives or state when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, lowering the burden. The description adds the unit of timestamp (seconds) and the historical aspect, but it does not disclose behaviors like error handling or what happens if the username is unknown. This is acceptable given the strong annotations but not rich behavioral detail.

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

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

The description is a single, front-loaded sentence that conveys the essential action and use case without any redundant wording 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?

As a simple read-only lookup with two parameters and an output schema, the description is largely sufficient. It covers the core 'at timestamp' nuance and the historical use case. It could be more complete by explicitly referencing the sibling tool for current UUIDs, but this is minor given the low complexity.

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

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

Schema coverage is 0%, so the description must add meaning to the parameters. It explains that 'username' is a Minecraft username and 'timestamp' is in Unix epoch seconds, which is helpful. However, it does not clarify that timestamp is optional (per schema) or what default behavior occurs without it, leaving a gap for the 0%-coverage 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 resolves a Minecraft username to a UUID 'at a given Unix epoch timestamp', which is a specific verb+resource+scope. It distinguishes itself from the sibling 'username_to_uuid' (which likely returns the current UUID) by emphasizing historical 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?

The phrase 'useful for historical name lookups' implies when to use this tool, but it does not explicitly name any alternative or when not to use it. Clear context is provided, but exclusions are missing, making it slightly less explicit than the ideal.

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

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

Annotations already indicate readOnly/idempotent/non-destructive behavior. The description adds substantial behavioral detail: the two distinct processing paths (SEC EDGAR vs grounded), the meaning of could_not_verify as a non-result rather than evidence, the distinction between could_not_verify and unsupported, and the citation format. It also warns callers not to present could_not_verify as evidence, which goes beyond schema/annotations.

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

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

The description is long (~180 words) but each sentence carries unique value: trigger phrases, usage, pipeline details, return values, and a critical caller warning. It is front-loaded with purpose and structured logically, though slightly verbose for the complexity involved.

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

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

Despite no output schema, the description fully explains the return structure (verdict types, actual value with citation, reasoning) and error semantics (could_not_verify with verification_error, unsupported meaning). This covers edge cases and gives a complete picture for a complex tool, making it highly usable without additional documentation.

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

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

Schema coverage is 100% for both parameters. The description adds extra meaning by providing concrete examples of claim statements and explaining tolerance_pct semantics: it overrides the implied tolerance, has a range/cap, and suggests 1-2 for hallucination detection. This enhances understanding 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 defines the tool as natural-language claim verification against authoritative sources, listing trigger phrases like "fact check" and "verify the claim that." It distinguishes itself from sibling tools by specifying the verdict-based output and the replacement of 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?

It explicitly states when to use it: "Use whenever the agent needs to check whether something a user said is factually correct." It also differentiates between company-financial claims (SEC EDGAR path) and other claims (grounded pipeline). However, it does not name specific alternatives or explicitly state when not to use it, so it lacks full exclusion guidance.

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