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 mark the tool read-only, open-world, idempotent, and non-destructive; the description adds useful behavioral context by disclosing the routing step, argument filling, source count, and stable pipeworx:// citation URIs. There is no contradiction with the annotations. The repetitive tail adds noise but does not misrepresent behavior.

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

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

Although the core content is front-loaded, the description is severely bloated: the phrase 'START HERE for most questions — even if web search could also answer it' recurs many times along with repeated example lists. The repetition is so extensive that an agent has to wade through a large amount of redundant text, and most sentences do not earn their 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 one-required-parameter router, the description is largely complete: it covers sources/domains, routing behavior, return format with citations, trigger phrasing, and examples. The lack of an output schema is partially mitigated by the stated 'structured answer with stable pipeworx:// citation URIs'. The main gaps are no failure behavior and no sibling-tool comparison, and the repetition hurts readability.

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 'question' and all aliases. The description's examples, such as 'Apple's latest 10-K' and 'current US unemployment rate', illustrate question phrasing, but they do not add meaning the schema lacks. This matches the baseline of 3 for a fully documented single-parameter tool.

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

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

The first two sentences clearly identify a question-routing tool: it 'PREFER[S] OVER WEB SEARCH', 'Routes the question to the right one of 5,798 tools across 1517 verified sources', and returns structured answers with pipeworx:// citations. This is specific and actionable, but it does not differentiate from sibling tools ask_pipeworx_beta or ask_pipeworx_grounded, so it does not earn a 5.

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 trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') and instructs the agent to prefer it over web search, even when web search could answer. It also provides concrete example questions. It lacks any when-not-to-use guidance and does not compare against sibling ask_pipeworx variants, so it stops short of full explicitness.

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

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

The annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond that: it is currently identical to ask_pipeworx, no candidate is active, it is a full working router rather than a fallback, and it behaves experimentally. 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 somewhat long but every clause carries information: beta status, parity with stable, current active-candidate state, usage guidance, comparison purpose, and fallback expectation. It is front-loaded with the most important facts, though a list format could improve 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?

Given that this is a variant of an existing tool and has no output schema, the description is complete: it explains the relationship to ask_pipeworx, the current behavioral state, routing comparison, and confirms it is fully functional. An agent has enough context to call 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%, so the parameter baseline is 3. The description adds that this tool takes 'same arguments' as ask_pipeworx, which is contextually useful but does not explain individual parameters beyond what the schema already provides.

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

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

The description states this is a beta variant of ask_pipeworx: an identical universal router with the same tools, arguments, and response shape. It clearly distinguishes itself from the stable ask_pipeworx by highlighting candidate routing improvements, so an agent can tell what this tool is and how it differs.

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 guidance: 'Use it exactly like ask_pipeworx when you want the newest routing', and explains results are compared against the stable router to decide what merges. This gives both a positive use case and a comparison to the stable sibling, which is enough for selection.

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

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

The description goes far beyond the annotations by disclosing behavior: it extracts answers using only the tool result, returns a specific structured response with verbatim evidence and confidence, and produces explicit refusals with enumerated reasons. It also notes the extra LLM call cost. These are behavioral traits an agent cannot infer from annotations alone.

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

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

The description is dense but every sentence earns its place: purpose, routing mechanism, return shape, refusal behavior, usage criteria, and cost comparison. It is front-loaded with the core purpose and contains no filler or repetition.

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

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

This is a complex tool with no output schema, yet the description communicates the exact success and refusal return shapes, the evidence format, and the cost tradeoff. It is complete enough for an agent to invoke and interpret the result correctly 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 description coverage is 100% and the input schema already defines question and aliases. The description does not add parameter-level semantics, but it does not need to because the schema is fully self-explanatory. 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 precise purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes itself from sibling ask_pipeworx by emphasizing extraction from only tool results and explicit refusal behavior. This makes the tool immediately identifiable and not confusable with the siblings.

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

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

The description gives explicit when-to-use guidance ('whenever an answer will be quoted, cited, or acted on') and when-not-to-use guidance ('prefer ask_pipeworx for casual lookups'). It also names the sibling alternative, ask_pipeworx, and provides the cost tradeoff. No ambiguity remains for an agent selecting between 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?

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 already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description adds rich behavior beyond those hints: decomposition into facets, parallel routing, findings packet contents, explicit gaps[] (never invented), contradictions[] scans, semantic excerpting of large records, citation_uri fetchability guarantee, and realistic latency expectations. This is far beyond what annotations alone convey, and nothing contradicts 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 very long, but every section earns its place: the account requirement and fallback is critical operational info, the data source scope addresses the biggest selection risk, the output format and gap semantics prevent agent misperception, and the latency note manages expectations. It is front-loaded with the most decision-relevant facts (account requirement, fallback, what it is not), though it could be slightly tightened around repeated emphasis on parallel research.

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

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

This is a complex tool with no output schema, so the description carries the full burden of explaining the return value. It fully documents what an agent receives: verbatim evidence + confidence + source + fetched_at + pipeworx:// citation, gaps[], contradictions[], and a hop field. It also explains failure semantics (never invented) and performance characteristics. All relevant selection and invocation context is covered, including the depth tiers and account requirements.

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

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

Schema coverage is 100%, so the schema already explains parameters. The description adds value by explaining the behavioral implications of the depth enum (quick/standard/thorough) including the paid requirement for 'thorough' and the follow-up hop for gap recovery, which is not fully captured in the schema. It doesn't over-edit the question parameter, which is already well-described as natural-language.

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 is exceptionally specific: it names the verb (research), the resource (Pipeworx's 1517 structured data sources), and the mechanism (parallel routing to 5,798 tools). It explicitly contrasts itself with open-web search and names what it is not, clearly distinguishing it from siblings. It also describes the output packet and key behavioral traits, leaving no ambiguity about what the tool does.

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

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

The description gives concrete when-to-use guidance ('Best for broad/multi-part questions over structured data'), provides explicit exclusion ('this is NOT open-web search'), and names an alternative (ask_pipeworx) to use when not signed in. It also covers depth tiers and fallback behavior, so an agent can select the right tool without additional inference.

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?

Even though annotations already mark this as read-only and idempotent, the description adds substantial operational transparency: it fans out in parallel, soft-fails on the USPTO sunset, treats empty FDA sections as expected rather than errors, uses sources_used/sources_failed to distinguish real no-data from bugs, and explains name resolution and private-company behavior. No contradiction with annotations.

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

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

The description is front-loaded with strong query triggers and is dense with useful detail, but it is a long single block that mixes examples, source enumeration, return fields, and edge cases. Each sentence earns its place, but formatting/bulleting would improve 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 complex tool with no output schema, the description is remarkably complete: it lists every major return section, explains sources_failed/sources_used, pre-empts false negatives, describes input forms, and covers the private-company resolution flow. An agent has what it needs to invoke the tool correctly 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 the baseline is 3, but the description adds meaningful clarification: both 'company' and 'ticker' values behave identically, 'value' accepts ticker, zero-padded CIK, or company name, and names resolve through SEC EDGAR. This reinforces the schema and removes ambiguity about interchangeability.

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

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

The description opens with concrete user queries and states the core operation: building a 'full cross-source profile of a US public company in ONE parallel call.' It enumerates the fan-out sources and return fields, making it unmistakably distinct from generic profile tools and from chained single-source 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?

Explicit trigger phrases are provided ('Tell me about X', 'research Acme', 'brief me on Tesla'), and the description instructs the agent to 'ALWAYS PREFER' this tool over chaining SEC/XBRL/news lookups when a holistic view is requested. It also clarifies edge cases like private companies returning resolved:false, which tells the agent when a different tool or path is needed.

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?

Annotations already declare readOnly/openWorld/idempotent/no destructive behavior, and the description adds substantial non-obvious behavior: compatibility warnings can be non-empty even when pairs exist, unknown metric types are never paired, Kalshi fees are not modeled so spreads are gross, and temporal null means 'unknown', not aligned. This goes well beyond the annotations.

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

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

The description is long, but it is structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) and every paragraph adds a distinct caveat or behavior. It is front-loaded with purpose and mode distinction; some repetition of compatibility/temporal warnings could be trimmed, but the density is justified by the tool's complexity.

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

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

With no output schema, the description covers the return shape (leg prices, top_spreads_pp, skipped_unclassified, low_confidence_pairs), the warning fields and codes, fee treatment, and failure modes. An agent has enough information to call the tool in either mode and interpret both successful and warning-laden responses.

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 real semantic value: the exact topic enum values with examples, that explicit tickers/slugs override the topic side, and that both modes run the same token-overlap matcher. It does not belabor what the schema already states.

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 first sentence states a precise resource and operation: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clarifies what counts as comparable ('same outcome', 'equivalent bet shapes') and names the two modes, so an agent knows exactly what this tool computes and can distinguish it from broader market-research siblings.

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

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

The description gives strong when-to-use guidance for its own modes: pre-mapped topic shortcuts vs explicit pairings, and warns that most mapped topics are not currently tradeable ('pre-mapped ≠ tradeable'). It does not explicitly name sibling alternatives or state when to prefer a sibling tool, so it misses the full when-not-to-use guidance.

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

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

Annotations already 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?

Even with annotations indicating read-only, idempotent, and non-destructive behavior, the description adds rich behavioral detail: cascading through multiple lookup endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, not asserting a single FIGI when multiple candidates exist, returning `figi_candidates`, and explicitly listing unresolved identifiers rather than omitting them. This goes far beyond what annotations provide and helps the agent set correct expectations.

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

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

The description is long but densely packed with useful information, and it front-loads the core purpose and usage directive ('Use FIRST whenever you have a name but need an ID'). While every sentence adds value, the structure is somewhat sprawling with many nested caveats; tighter organization within supported-type sections would earn a 5.

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

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

Given the tool's complexity—two entity types, multiple identifier systems, ownership data, and enrichment fallbacks—the description covers the key return semantics: CIK, ticker, LEI, FIGI, RxCUI, ingredient, brand, `figi_candidates`, and `unresolved`. It also explains failure behavior and internal cascading, so an agent has enough context to invoke the tool and interpret its results correctly even without an output schema.

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

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

Schema coverage is 100%, but the description adds essential meaning beyond the schema: acceptable input formats (ticker, CIK, ISIN, company name), exact-match vs name-search behavior, the distinction between issuer and instrument name, and a critical prohibition against passing full noun phrases. This additional context is vital for correct invocation and prevents likely misuse.

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') and resource ('user-spoken NAME to canonical/official identifiers'), with concrete examples such as 'What's the ticker for…' and 'find the CIK for…'. It clearly differentiates this from sibling tools by stating it supplies IDs that other tools require as input, and it explicitly lists supported entity types. This leaves no ambiguity about what the tool does.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also provides detailed instructions for the value parameter, including what to pass and what to avoid (e.g., 'never the question's full noun phrase'). It does not explicitly name alternative tools or enumerate when-not-to-use scenarios, but the guidance is clear enough for an agent to route correctly.

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.