Httpbin

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive. The description adds value by revealing cost implications ('BYO key – you pay Anthropic directly'), default model selection, and return structure (per-model fields + combined view). No contradictions.

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

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

Four well-structured sentences, no wasted words. Purpose is front-loaded, followed by conditional details and use cases. Ideal conciseness.

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

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

Explains return format despite no output schema, covers all parameters and their interactions, and gives concrete use cases. Lacks error handling or edge cases, but acceptable for a read-only tool with good annotations.

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 good parameter descriptions. The description goes further by tying models to _apiKey dependency and explaining default behavior, which adds semantic value beyond the raw 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 probes LLMs for brand visibility and returns a 0-100 score per model. It specifies the resource (LLMs), action (probe), and output format. While sibling differentiation isn't explicit, the tool's unique purpose is 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 cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains conditional usage (default free model vs. BYO key for Anthropic). Lacks explicit when-not or alternative tool mentions, but the context is clear.

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

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

Beyond the readOnly/idempotent annotations, the description explains routing behavior, argument-filling, 'one fast call', 'works on every tier', and the stable 'pipeworx:// citation URIs' return format. No contradiction with annotations exists.

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

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

The text is front-loaded with the primary instruction and uses clear structural signposts ('START HERE', 'Step up only when needed'). It is longer than strictly necessary due to broad domain lists and examples, but the length serves the tool's wide scope.

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 general-purpose read-only question router with no output schema, the description fully covers what to ask, when to use it, when not to, what output to expect, and examples. The only missing detail would be error/limitation behavior, which is not essential for this tool.

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

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

Schema description coverage is 100%: all six parameters are documented aliases for a single natural-language question. The description adds examples and query style, but no additional parameter-level semantics beyond the schema.

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

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

The description names a precise verb and resource: ask_pipeworx 'routes the question to the right one of 5,724 tools across 1497 verified sources' and returns an answer with citations. It distinguishes itself from siblings by stating when to step up to ask_pipeworx_grounded or deep_research, and it clearly frames itself as the default question-router.

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 opens with 'PREFER OVER WEB SEARCH' and gives an explicit default rule: 'START HERE for most questions'. It also provides concrete alternatives with selection criteria: ask_pipeworx_grounded for verbatim evidence + confidence, deep_research for broad/multi-part questions, and it covers breaking-news routing.

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 meaningful behavioral context beyond the annotations: it is a live experimental router, candidates are toggled on/off, results are compared against the stable router to decide merges, and it is a full working router with no fallback. This fully transparent picture helps the agent understand the tool's runtime behavior.

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

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

The description is somewhat long but every clause adds useful context: beta relationship, identity with ask_pipeworx, current experimental state, routing comparison, and no-fallback clarification. It is front-loaded with the most important identification ('Beta version of ask_pipeworx') and does not waste words, though it could be trimmed slightly.

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

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

For a universal router with no output schema, the description gives enough context to call it correctly: it is a full working router, same arguments as ask_pipeworx, same response shape, and currently matching stable behavior. It does not enumerate what kinds of questions work, but 'universal router' plus the schema's natural-language prompt field make the usage clear. Slight gap is that the agent is expected to infer the response shape from ask_pipeworx rather than having it spelled out here.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases of the required 'question' parameter. The description adds no parameter-level information, but none is needed because the schema already fully explains the input contract. Baseline 3 is appropriate since the schema carries the semantic load.

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

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

The description states a specific verb ('Ask') and resource ('Pipeworx Beta'), and clearly defines it as a beta version of ask_pipeworx with the same 5,724 tools, arguments, and response shape. It is explicitly distinguished from the stable ask_pipeworx and is not conflated with ask_pipeworx_grounded, so an agent can tell the tools apart.

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 clear when-to-use guidance: use it exactly like ask_pipeworx when you want the newest routing, and results are compared against the stable router. It also states that no candidate is active currently, so behavior currently matches ask_pipeworx. It does not explicitly mention when to prefer ask_pipeworx_grounded, but the main routing decision between beta and stable is well covered.

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

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

Discloses significant behavior beyond the annotations: the return object shape with answer and evidence fields, the explicit refusal cases with a refusal_reason enum, and the extra LLM call cost. Annotations (readOnly, idempotent, non-destructive) match the described behavior, with no contradiction.

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

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

The description is dense but every clause earns its place: core mode, routing behavior, grounding guarantee, return shape, refusal semantics, high-stakes use cases, and cost trade-off. The most important differentiator ('only what the tool result contains') is front-loaded, and the guidance ends with a clear preference rule.

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

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

Despite having no output schema, the description fully specifies the success return shape, the failure/refusal shape, the possible refusal reasons, and the cost implication. It also situates the tool among siblings (ask_pipeworx, ask_pipeworx_beta) sufficiently for an agent to choose and 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%, with all six parameters documented as aliases for the natural-language question. The description adds no new parameter-level meaning beyond restating that the tool 'fills arguments', but because the schema fully covers the parameter semantics, the 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 states a specific mode ('hallucination-resistant answer mode') tied to a concrete behavior: route the same way as ask_pipeworx, fetch data, and extract answers using only the tool result. It also explicitly distinguishes itself from ask_pipeworx by naming the sibling and the differentiator (grounded extraction, refusal behavior). The resource and operation are immediately clear.

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

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

Provides explicit when-to-use guidance ('whenever an answer will be quoted, cited, or acted on...'), explicit when-not-to-use ('prefer ask_pipeworx for casual lookups'), and a concrete trade-off ('costs one extra LLM call'). The alternative is named and the decision rule 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?

The description adds zero behavioral context beyond what annotations already declare (readOnlyHint, idempotentHint, etc.). It does not disclose any traits like error behavior, output format, or side effects. With annotations present, the description should at least confirm or elaborate on them.

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

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

The description is extremely short (2 words), but this is under-specification, not conciseness. It does not earn its place because it adds no valuable information. A one-word description is not acceptable for a tool with one parameter.

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 there is an output schema and only one parameter, the description is incomplete. It does not explain what the output represents, how errors are handled, or any edge cases. The tool is simple, but the description fails to cover even basic usage.

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% (no parameter descriptions in the schema or description). The description fails to explain the required parameter 's', its type, expected format, or examples. Despite having 1 parameter, the description provides no assistance, leaving the agent blind about input requirements.

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 'Base64 decode' is a tautology that merely restates the tool's name. It lacks specificity about what the tool does (e.g., decode a base64-encoded string to its original representation) and does not differentiate it from the sibling tool 'base64_encode'.

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?

No usage guidance is provided. The description does not indicate when to use this tool compared to alternatives like base64_encode or any other decode functionality. It fails to mention prerequisites, limitations, or appropriate contexts.

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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description adds little behavioral context. It does not contradict annotations, but also does not disclose any additional traits (e.g., output format or 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 a single short sentence, which is concise. However, it sacrifices clarity for brevity, leaving out important details. It could be slightly longer without becoming verbose.

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

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

Given the tool's simplicity and the presence of an output schema, the description is nearly complete but fails to explain the input parameter. For a trivial encoding tool, this is acceptable but not exemplary.

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%. The parameter 's' is left undocumented in the description. While the name and type suggest it is the input string, the description should explicitly state its role and any constraints.

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 'Base64 encode.' clearly states the verb (encode) and resource (Base64), but it is extremely terse. It is not misleading and distinguishes from the sibling base64_decode, but lacks any additional context about what the tool does exactly.

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?

No guidelines are provided on when to use this tool versus alternatives like base64_decode. The description gives no context about appropriate use cases or prerequisites.

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

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

Annotations already mark it as read-only, idempotent, non-destructive. The description adds extensive behavioral detail: resolver contract, fan-out logic, response shapes, safety short-circuits for low-confidence matches, closed markets, wide spreads, resolution rules, and parent event extraction. No contradictions.

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

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

The description is lengthy but well-structured with clear topic sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every sentence adds value, though some could be streamlined. Overall, it effectively communicates complex functionality without excess.

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 all output fields and their meaning, including resolver confidence, parent events, news fields, safety mechanisms, and resolution rules. It covers edge cases (low confidence, closed markets, wide spreads) and provides enough detail for correct tool usage.

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 description adds meaning: market parameter accepts slug, URL, or question text; depth controls quick vs thorough fan-out; include_raw defaults to false for summarized responses. This goes beyond the 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 states it researches a Polymarket bet by pulling Pipeworx data in one call. It specifies input formats (slug, URL, question text) and output (evidence packet + comparison). It distinguishes from siblings like polymarket_edges and polymarket_arbitrage by its focus on data gathering and evidence.

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: 'Use for should I bet on X, what does the data say about Y, or is there edge in Z.' It implies alternatives exist (e.g., polymarket_edges for pure edge detection) but does not explicitly state when not to use this tool. Still, the context is clear enough.

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

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

Annotations already indicate safe, idempotent read-only behavior. Description adds valuable context: pulls SEC EDGAR/XBRL for companies, FAERS/FDA for drugs, handles off-calendar fiscal years, sorts by primary metric, and returns citation URIs. No contradictions.

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

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

Single dense paragraph with front-loaded examples and clear structure. Every sentence adds value, though slightly verbose; could be trimmed without loss.

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, description mentions return type (paired data + citation URIs). Lacks explicit output structure but sufficient for a simple tool with 2 params and no nested objects.

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

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

Schema already has 100% coverage with descriptions. Description adds further detail: explains what type='company' vs 'drug' entails, specifies tickers/CIKs for companies and drug names, and clarifies max/min items.

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

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

Description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It provides example queries like 'X vs Y' and 'which is bigger', and distinguishes from siblings by explicitly preferring over sequential single-pack 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?

Explicitly says when to use (comparing entities, replaces 8-15 sequential lookups) and provides context on data sources and handling of fiscal years. The 'ALWAYS PREFER' directive gives clear guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds no behavioral context beyond these structured fields, failing to add value.

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 extremely concise at two words, but under-specifies the tool's purpose. While brevity is good, it does not earn its place by being informative.

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 an output schema and no parameters, the description is too vague. An agent would not understand what 'Caller cookies' means or what action the tool performs.

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 zero parameters and 100% schema coverage, the baseline is 4. The description does not add parameter meaning, but it is not required since there are no 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 'Caller cookies.' is a noun phrase without a verb, failing to state whether the tool gets, sets, or lists cookies. It does not specify the resource or action clearly, making it ambiguous.

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?

No guidance on when to use this tool versus alternatives like headers or user_agent. It does not provide context, prerequisites, 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?

Despite annotations already declaring readOnly, openWorld, idempotent, and non-destructive traits, the description adds substantial behavioral context: it is not open-web search, it never invents answers (gaps[]), it performs second-hop iteration for uncovered facets, it returns contradictions[] for standard/thorough depths, and it only returns fetchable citations. It also discloses timing (15-60s, up to ~90s for thorough). 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 highly information-dense, with every sentence earning its place. It is logically structured: account requirement first, then alternatives, core mechanism, use cases, depth behavior, timing. It front-loads critical constraints (account needed, alternatives) and avoids redundancy.

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

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

With no output schema, the description fully specifies the return value: a findings packet with verbatim evidence, confidence, source, fetched_at, a stable pipeworx:// citation, explicit gaps[], contradictions[] (for standard/thorough), a hop field, and a citation_uri only when fetchable. It also covers edge cases like large-record excerpting and timing. Nothing an agent needs to invoke and interpret the tool correctly is missing.

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

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

The input schema already documents both parameters (question and depth) with 100% coverage. The description goes further by elaborating the depth enum: quick=3 facets single-hop, standard=3 with gap-recovery hop + contradictions scan, thorough=6 paid with iterative chasing and contradictions scan. It also clarifies that 'thorough' requires a paid plan, adding meaning beyond the schema.

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

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

The description precisely defines the tool's function: grounded multi-source research across 1497 structured data sources, decomposing the question into facets, routing in parallel to 5,724 tools, and returning a findings packet with evidence, confidence, source, fetched_at, and citations. It clearly distinguishes itself from ask_pipeworx and open-web search, making it unambiguous.

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

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

The description explicitly states when to use this tool ('Best for broad/multi-part questions over structured data') and when not to ('For a single lookup use ask_pipeworx'; 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'). It also provides account prerequisites and directs unsigned-in users to ask_pipeworx, covering both positive and negative usage cases.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds only 'Sleep N seconds,' which does not disclose additional behavioral traits (e.g., blocking nature, precision). Minimal value beyond annotations, but no contradiction.

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

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

Extremely concise: two words. Front-loaded with the essential action. No superfluous content.

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

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

Given the tool's simplicity, an output schema exists (not shown) and annotations cover safety. However, the description omits details like blocking behavior, return value, or precision. Adequate for a minimal tool but leaves gaps for an agent needing complete understanding.

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% for the 'seconds' parameter. The description implies N is the number of seconds but does not specify range, data format (e.g., float allowed), or unit beyond 'seconds.' Examples in schema provide some context, but description insufficiently compensates for the lack of parameter documentation.

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

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

Description 'Sleep N seconds' clearly states the verb (sleep) and resource (time delay), distinguishing it from all sibling tools as uniquely performing a time delay. No ambiguity.

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?

No guidance on when to use this tool versus alternatives or when not to use it. The sibling list includes many tools but none are similar, yet the description provides no context for appropriate usage scenarios.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is clear. The description adds behavioral details: returns top-N relevant tools with schemas and examples, results are call-ready. No contradictions, and the description enhances understanding of the tool's behavior 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 concise with no redundant sentences. It front-loads the main purpose and usage, then adds key details about return format and when to call. Every sentence is informative and 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?

Given the tool's simplicity (one required parameter, optional limit), the description fully covers purpose, usage, return value, and context. No output schema exists, but the description sufficiently explains what the agent will receive. Examples in the input schema further aid understanding.

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 reinforces that 'query' accepts natural language and gives examples, but does not add significant new semantic meaning beyond what the schema provides.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and explains that it returns relevant tools with full schemas, ready to call. It distinguishes itself from sibling tools by advising 'Call this FIRST' when exploring many tools.

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

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

The description explicitly tells when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist for ...' and 'Call this FIRST when you have many tools available.' It provides clear guidance on discovery versus direct querying.

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

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

The description adds behavioral details beyond annotations: it fans out across multiple sources, lists return fields, and notes the USPTO sunset soft-fail. Annotations already indicate readOnly, idempotent, openWorld, non-destructive; description enriches context without contradiction.

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

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

The description is informative but slightly verbose and runs on. It packs many details into a single paragraph; a more structured list would improve readability. However, it is still concise relative to the information conveyed.

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 data: CIK, filings, fundamentals, patents, news, LEI. It also covers edge cases (sunset, soft-fail, name not supported). This is complete for a complex tool.

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

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

Schema coverage is 100%, but the description adds crucial semantics: type is limited to 'company', value must be ticker or zero-padded CIK, names not supported. This goes beyond the schema enum and description.

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

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

The description clearly states the tool's purpose: providing a full cross-source profile of a US public company in a single call, with specific examples and a list of returned data sources. It distinguishes itself from chaining single-pack 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?

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and specifies that names are not supported, directing to use resolve_entity first. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds that it deletes a memory, which is consistent, but provides no additional behavioral context like side effects or required permissions.

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 that efficiently convey purpose, usage, and relation to siblings. Front-loaded with the primary 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 simple delete operation with one parameter and no output schema, the description adequately covers action, usage guidelines, and related tools. No missing critical information.

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

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

Schema coverage is 100% with the 'key' parameter described as 'Memory key to delete'. The description adds no extra meaning beyond the schema, 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 action ('Delete'), resource ('previously stored memory'), and method ('by key'). It distinguishes from sibling tools 'remember' and 'recall' by explicitly mentioning deletion.

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 scenarios for use: when context is stale, task is done, or clearing sensitive data. It also suggests pairing with 'remember' and 'recall', though it doesn't explicitly state when not to use it.

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

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

Annotations already declare it as safe, idempotent, non-destructive. Description adds details about fetching page, extracting metadata, and output format. No contradiction.

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

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

Single paragraph, front-loaded with main purpose. Efficient but could be slightly more structured. 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?

With 2 well-documented parameters, annotations, and no output schema, the description adequately covers what the tool does and its output format.

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

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

Schema coverage is 100% with descriptions for both parameters. Description repeats url description with example but adds no new semantic meaning beyond schema.

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

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

Clearly states it generates an llms.txt file for any URL, with specific verb 'generate' and resource 'llms.txt file'. Distinct from siblings like robots_txt.

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 lists use cases: getting client's site indexed, drafting for own project, auditing competitor. Does not specify when not to use, but context is clear.

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

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

Description adds that the tool echoes the request, including query parameters, headers, origin IP, and User-Agent. Annotations already declare readOnlyHint and idempotentHint, so no contradictions. The description adds some behavioral context but doesn't discuss error handling or limits.

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 action and return info, followed by use case. No unnecessary words or redundancy.

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

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

Given the tool's simplicity and the presence of an output schema, the description covers the purpose and return data well. Could be more explicit about the output format, but overall sufficient for debugging.

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%, and the description only repeats parameter names ('query object', 'custom headers') without detailing what properties they accept or their formats. The examples in the schema provide some context, but the description itself adds minimal 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?

Description clearly states the tool sends a GET request to httpbin.org and returns echoed request data, specifying return fields. However, it does not explicitly differentiate from sibling tools like 'post', though the verb 'GET' implies the method.

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?

Says 'Use for HTTP debugging', which provides context but no explicit when-not-to-use or alternative tools. The implied usage is clear but lacks 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, idempotentHint, and destructiveHint false. Description adds 'Echo caller's headers' which is consistent but minimal 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?

Single, front-loaded sentence with no redundancy. Efficient.

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

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

For a zero-parameter, simple echo tool with output schema, description is sufficiently complete.

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

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

No parameters exist. Schema coverage is 100%. Description does not need to add parameter details.

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

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

Description 'Echo caller's headers' provides a specific verb and resource. It clearly distinguishes from sibling tools like get or post.

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?

No usage guidance provided. Does not indicate when to use this tool over alternatives or prerequisites.

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

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

Annotations already convey read-only and idempotent behavior. The description adds that it fetches from httpbin.org (/html), confirming the resource. No further behavioral details (e.g., rate limits) are provided, but annotations cover safety.

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 with no filler. The key information is front-loaded.

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 parameterless tool with an output schema, the description fully covers what the tool does and why to use it. No gaps.

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

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

There are no parameters, so schema coverage is 100%. The description adds no extra param info, which is acceptable. Baseline 4 applies for zero 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 action ('Fetch a sample HTML response from httpbin.org (/html)') and specifies its purpose ('verify HTML content-type handling or as a placeholder in tests'). It distinguishes from sibling tools like json_anything or xml_anything.

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 (verifying HTML handling, placeholder in tests) but does not mention when not to use it or alternatives. However, given the simplicity, this is clear enough.

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 safe. The description adds that it returns a URL, which is consistent. However, it does not disclose potential side effects (none expected) or rate limits, but annotations carry the burden.

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

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

Single sentence, very concise and front-loaded. However, it sacrifices substance for brevity, omitting necessary detail. Every word earns its place, but it fails to be informative.

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

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

With one parameter and rich annotations, the description still needs to clarify the tool's function and parameter role. 'Sample' is vague. The lack of output schema visible (though context says present) reduces completeness. The description is insufficient for an agent to use 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 0%, and the tool description does not mention the 'format' parameter. The schema only gives examples (png, jpeg) without explaining valid values or default. The agent has no semantic info about the parameter beyond its type.

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 'Sample image metadata (returns URL)' indicates the tool returns a URL, but 'sample' is ambiguous (test data vs. real placeholder). The name 'image' and input format parameter suggest image generation, but the purpose is not fully explicit. It distinguishes from siblings by name only.

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

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

No guidance on when to use this tool versus alternatives. The description does not specify context, prerequisites, or that it provides placeholder images. The agent receives no help deciding when to invoke it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false, establishing it as a safe, idempotent read. The description adds the specific context of 'gateway egress' but does not contradict 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, concise phrase with no unnecessary words. Every word 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 zero-parameter tool with annotations and an output schema, the description 'Caller IP (gateway egress)' provides sufficient context to understand what the tool returns.

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

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

The tool has zero parameters, and schema description coverage is 100%. The description does not need to add parameter details; baseline for no params is 4.

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

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

The description 'Caller IP (gateway egress)' clearly states the tool returns the IP address of the calling client from the gateway egress perspective. It distinguishes itself from sibling tools by being the only IP-focused 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?

No explicit guidance on when or when not to use, but given the lack of sibling alternatives for IP lookup, the usage context is implied. No exclusions are mentioned.

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, destructiveHint=false, so description needs only to add context. It adds that the response is from httpbin.org and is a placeholder, which is valuable but not essential beyond annotations.

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

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

Two concise sentences with no redundant language. Every word adds value: 'Fetch a sample JSON response' and the use cases are front-loaded.

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 tool simplicity (no params, output schema present), description fully covers purpose and typical usage. No additional info needed.

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 has zero parameters, so schema description coverage is 100%. Description adds no parameter info but provides context about the returned data, which is helpful.

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

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

Description clearly states the verb 'Fetch' and the specific resource 'sample JSON response from httpbin.org (/json)'. It distinguishes from siblings like xml_anything by focusing on JSON.

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

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

Explicitly says when to use: 'to verify JSON content-type handling or as a placeholder in tests'. Implies testing/validation context, though doesn't explicitly mention when not to use.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds the specific return fields but does not elaborate on behavioral traits beyond what annotations provide. It does not contradict 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 covering action, return fields, and usage guidance. It is concise, front-loaded, and contains 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?

The tool is simple with one optional parameter and no output schema. The description explicitly lists the return fields and provides usage context, making it complete for an agent to invoke correctly.

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

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

The input schema has one optional parameter (include_inactive) with full schema description. The tool's main description does not add extra meaning to this parameter beyond the schema, so baseline 3 applies.

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

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

The description clearly states the tool lists the caller's active subscriptions and lists the fields returned. It distinguishes from sibling tools like subscribe and unsubscribe, which are action-oriented.

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 context for when to use it: to review monitored subscriptions before adding more or to find an ID to cancel. It does not explicitly state when not to use it or list alternatives, but the guidance is clear.

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

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

Despite annotations conveying little (all hints false), the description discloses rate limiting ('5 per identifier per day'), account-less behavior (returns a claim_token), the retrieval flow, daily digest handling, and the fact that it does not count against quota. This goes well beyond the annotation fields.

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

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

The description is longer than average but every sentence contributes meaningful guidance, such as scope limitations, token usage, and feedback quality. A slight trim of motivational lines ('signal directly affects roadmap') could improve conciseness, but overall it is well-structured and front-loaded.

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 feedback tool with no output schema, the description fully explains what to expect (claim_token), how to follow up, the rate limit, the free/quota status, and what constitutes appropriate feedback. It also addresses edge cases like cross-server provenance, making it exceptionally complete.

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

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

Although schema coverage is 100%, the description adds significant semantic value: it explains the claim_token parameter's role with a concrete example, warns against pasting end-user prompts, and gives examples for context fields ('pack' -> 'fred', 'tool' -> 'fred_get_series'). This enhances the schema's bare 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 identifies the verb ('Tell'), the resource ('Pipeworx team'), and the purpose ('something is broken, missing, or needs to exist'). It also distinguishes itself from sibling tools by enumerating specific feedback categories (bug, feature, data_gap, praise) and explicitly contrasts with other MCP servers' 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?

Provides explicit when-to-use conditions (e.g., wrong/stale data, missing tool, surprising success) and an explicit when-not-to-use rule ('if the tool came from a different MCP server... file it with that server instead'). Also offers a disambiguation heuristic ('Pipeworx tool names are the ones this connection lists').

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. Description adds caching behavior (5min-1h), data source (CF analytics-engine), and privacy (no PII) 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?

Front-loaded with main purpose, then use cases, then technical details. Every sentence adds value, concise without being sparse.

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, description explains return type (top tools, packs, call volume). Parameters fully covered. Complete for a read-only analytics tool.

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

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

Schema covers window parameter with enum and description. Tool description adds contextual tradeoffs (short windows for hotness, long for steady-state), adding 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 clearly states it returns top tools, packs, and call volume over a window, distinguishing it from sibling tools that provide specific answers or actions.

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 lists three specific use cases (discovering hot data, confirming canonical tools, aligning use case). Could mention when not to use or 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 comprehensively explains behavioral traits beyond annotations: the three scan modes, partition check logic, semantic anchor (Jaccard similarity), partition filter, fill check with live order book, and response structure. Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are consistent and the description adds significant context.

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 thorough and well-organized with clear sections (trending, event, topic, semantic anchor, partition filter, fill check). While dense, every sentence carries information; slight length 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?

Despite lacking an output schema, the description fully documents the return structure (opportunities[] with gap_pp, suggested_trade, reasoning, etc.) and all behavioral details (fill check, similarity filters, placeholder detection). It is complete for safe and effective use.

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

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

Schema coverage is 100%, but the description greatly enriches parameter meaning: defines what an event slug is, recommends usage, explains cross-event behavior with topic, and gives concrete examples. This goes far 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's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (trending scan, single-event, cross-event) and explicitly contrasts with sibling tools like polymarket_fill_risk and polymarket_edges.

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

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

The description provides explicit guidance on when to use each mode: no args for trending, 'event' for specific markets, 'topic' for cross-event scanning. It includes recommendations (event mode recommended for specific markets) and when not to trade (fill check with realizable_edge_pp ≤ 0).

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 provides extensive behavioral details beyond annotations: caching (1h at KV level), output structure with diagnostics, special handling of Fed bets, placeholder filters, and limitations like 'your edge may already be in the price.' Annotations already declare readOnlyHint=true, destructiveHint=false, which are consistent. No contradictions.

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

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

The description is long but well-structured: purpose, segments, output fields, knobs, caching. It is front-loaded with the main goal. While every sentence adds value, it could be slightly more concise by reducing some technical details that might be less relevant for agent selection.

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 9 parameters, no output schema, and complex response structure (by_segment with diagnostics), the description compensates fully. It explains output fields, diagnostics for empty segments, caching, and edge cases like Fed bet exclusion. An agent has enough information to correctly invoke the tool 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 significant context for parameters, such as explaining how min_partition_leg_kelly works for partitions where parent-level Kelly is zero, and how tradeable-edge knobs (min_liquidity, max_spread_pp) filter opportunities. This adds value beyond the schema's descriptions.

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

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

The tool's purpose is clearly stated: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the resource (Polymarket markets), action (scan and return opportunities), and differentiating factor (Pipeworx disagreement). This distinguishes it from siblings like polymarket_arbitrage or polymarket_edge_tracker.

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 the intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It explains the output segments (model_driven, structural_arbitrage, concentrated_longshot) and when they are applicable. However, it does not explicitly compare to sibling tools or state when not to use this tool, leaving some ambiguity.

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 readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds significant behavioral context: uses snapshots, shows time-series, calculates trend and decay, explains gaps, and notes decay numbers are from daily closes, not intraday. No contradictions.

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

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

The description is detailed but well-structured: purpose first, then response fields, then limits. It is not overly terse nor verbose. Some sentences could be streamlined, but overall it is efficient and informative.

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

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

Given no output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]), covers optional parameters, and addresses edge cases like gaps and limits. It is complete for an agent to understand and use the tool.

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

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

Schema coverage is 100% and includes descriptions. The description adds value by clarifying defaults, clamping (e.g., days 2-30), and behavioral context for window parameter. It goes beyond mere repetition.

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 provides 'edge persistence and decay telemetry' from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. It distinguishes between fresh and old edges, and gives a detailed response structure, making the purpose specific and differentiated from sibling tools like polymarket_edges.

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

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

The description implies use for analyzing edge longevity rather than current edges, noting that a fresh wide edge differs from a 3-week-old wide edge. It does not explicitly state when to use versus alternatives or provide exclusions, but the context is clear.

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

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

Description adds significant behavioral context beyond annotations: walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage, etc.), warns about forced directional risk and thin legs. 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 well-organized with headings for modes and returns all necessary information. While lengthy, every sentence adds value and it is front-loaded with core purpose. Slightly verbose but efficient overall.

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

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

Given the complexity (two modes, four parameters, no output schema), the description is complete: it explains inputs, outputs (lists all return fields), and caveats, fully compensating for the lack of 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 extra semantics: explains default logic for basket side, different interpretation of size_usd modes, and clarifies required usage for market vs event 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 as a realizable-vs-theoretical edge check against live order-book depth. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use it (before acting on arb signals or edges above ~$500).

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

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

Provides explicit guidance: use before arb signals or trades above $500, explains two modes (single-market and basket), gives prerequisites (requires market or event), and highlights risks of partial fills and thin books.

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?

This description goes far beyond the readOnly/idempotent annotations by detailing matcher behavior, compatibility codes, skipped pairs, low-confidence inspections, gross-vs-net fee disclosures, and the meaning of null temporal alignment. It discloses both what the tool does and where its output may be misleading. No contradiction with the annotations exists.

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

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

The description is long but well-organized with labeled sections for modes, response, safety fields, and codes. It is front-loaded with the core purpose and then layers necessary operational detail. Some redundancy exists around temporal_alignment_unknown and null semantics, but given the richness of the tool's output and the absence of an output schema, the length is largely justified.

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

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

With no output schema, the description carries the full burden of explaining the response shape and safety semantics, and it succeeds. It covers matched spreads, per-entry flags, compatibility warnings, skipped categories, fee modeling limitations, and temporal alignment behavior. An agent has enough context to interpret results correctly and avoid treating pre-mapped spreads as automatically tradeable.

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 documents all three parameters at 100% coverage, so the baseline is 3. The description adds meaningful semantics by explaining the two modes, that explicit ticker/slug overrides the topic-mapped side, and that both modes run the same matcher. It enriches parameter understanding without needing to restate schema text.

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

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

The description clearly identifies the tool's function: computing cross-venue spreads between Kalshi and Polymarket for matching resolving questions. It names the specific resource and explains the two input modes. However, it does not explicitly differentiate itself from sibling tools like polymarket_arbitrage, so distinguishing from alternatives is left somewhat implicit.

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 clear usage context: use topic shortcuts for pre-mapped macro events, or custom ticker/slug pairs for explicit pairings. It also warns that most pre-mapped topics currently return compatibility warnings and that pre-mapped does not mean tradeable. It stops short of naming specific sibling alternatives or explicit when-not-to-use conditions, so it misses the top score.

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 readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that the tool echoes the request with parsed JSON, form data, and headers. No contradictions.

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

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

The description is a single sentence that front-loads the action and quickly covers purpose and returns. No wasted words.

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

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

The tool has 3 parameters with no descriptions, and the description does not fully compensate. While the output schema exists, the description omits context about the tool's demo nature (e.g., 'use for testing'), leaving gaps for an AI agent.

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

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

With 0% schema description coverage, the description only mentions 'optional body and custom headers' vaguely. It does not explain the 'content_type' parameter or how headers should be structured. Examples in schema supplement slightly but not in description.

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

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

The description clearly states it sends a POST request to httpbin.org with optional body and headers. It distinguishes from siblings like 'get' (GET request) and 'headers'. The specific endpoint and method are clear.

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 does not explicitly state when to use this tool over alternatives. It is implied for POST requests to httpbin, but no exclusions or contexts are provided.

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

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

Annotations already indicate safe read operation; description adds scope and pairing 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?

Description is efficient and front-loaded, but slightly verbose with examples that could be condensed.

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 simplicity, good annotations, and no output schema, the description fully covers purpose, usage, and scope.

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, and the description adds no new detail beyond paraphrasing the schema's key description.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all saved keys, distinguishing it from sibling tools like 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?

Explicitly tells when to use the tool (look up context) and how (omit key to list all keys), with examples and scope details.

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 readOnlyHint and idempotentHint, but the description adds behavioral nuance: mark_read:true flags events as read, affecting subsequent calls. It also mentions polling suitability and the persistence of the feed, providing context beyond annotations without contradiction.

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

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

The description is concise yet informative, with purpose front-loaded. Each sentence adds meaningful context. Could be slightly tighter (e.g., combine filter details), but overall well-structured.

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

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

Given 5 optional parameters, no output schema, and no nested objects, the description covers return fields (source, citation_uri, raw payload), filter behavior, and mark_read side effect. It could mention limit pagination or unread_only behavior explicitly, but what's provided suffices.

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

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

With 100% schema coverage, baseline is 3. The description adds value by giving concrete filter examples (e.g., 'sec_8k') and explaining mark_read behavior (so the next call only shows newer ones), which 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?

Opens with 'Pull fired events from your subscription feed,' clearly identifying the action (pull/retrieve) and resource (fired events from subscription feed). Distinguishes from sibling tools like list_subscriptions and subscribe by focusing on event retrieval and mentioning specific filters (type, since) and mark_read behavior.

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

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

States 'Polls work fine' and provides a clear alternative endpoint for scripts/dashboards, indicating when this tool is appropriate. While it lacks explicit 'when not to use' guidance, the context is sufficient for typical usage.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. Description adds valuable behavioral context: sources consulted (SEC, GDELT, GNews, USPTO), fallback mechanism, the PatentsView API sunset soft-fail, and output structure with citation URIs. No contradictions.

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

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

Description is comprehensive yet efficient, front-loading common use-case phrases. Every sentence provides distinct value (scope, sources, fallback, alternative tool). Slightly lengthy but 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?

Given no output schema, description fully compensates by detailing return structure (changes grouped by source, total_changes count, pipeworx:// URIs). All 3 required parameters explained, behavior well-described, and sibling tool explicitly mentioned. Complete for an information-aggregation tool.

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

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

Schema covers all 3 parameters with descriptions. Description adds practical guidance: for 'since' it gives examples and recommends '30d' or '1m'; for 'value' mentions ticker or CIK; for 'type' clarifies only 'company' is supported. This exceeds schema-provided info.

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

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

Description clearly states it provides a change feed for a company covering SEC filings, news, and patents, with specific query examples. Explicitly distinguishes from sibling tool entity_profile by contrasting 'change feed' vs '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?

Provides explicit usage examples in natural language queries, specifies fallback logic between GDELT and GNews, and directly advises to use entity_profile for static profiles. No ambiguity about when to use this tool vs. 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?

Discloses scoping by identifier, persistence differences (authenticated vs. anonymous), and pairing with other tools. Annotations already indicate non-destructive and idempotent, but description adds valuable behavioral context without contradiction.

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

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

Front-loaded with main action; three sentences cover purpose, usage, and behavior. Efficient but could be slightly more concise.

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

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

Given simple parameters and no output schema, description fully covers purpose, usage, and behavioral traits. Complete for agent selection and invocation.

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

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

Schema covers 100% with descriptions for both key and value. Description adds examples but no additional semantic detail beyond schema. Baseline score 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?

Clear verb ('Save data') and resource ('the agent will need to reuse later'). Examples (resolved ticker, target address) and distinction from siblings recall and forget explicitly stated.

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

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

Explicit guidance: 'Use when you discover something worth carrying forward' and pairing with recall/forget. Provides context for when to use.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, but the description adds substantial behavioral detail: cascading through multiple lookup endpoints, graceful degradation when GLEIF/OpenFIGI fail, returning figi_candidates on ambiguity rather than asserting, labeling identifiers by source, and explicitly listing unresolved identifiers. This goes well beyond what annotations 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 and dense, but the length is largely justified by the tool's multi-source complexity. It is front-loaded with user-intent examples and structured by supported type, though a few parenthetical asides make it harder to scan than necessary.

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

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

Despite no output schema, the description explains what the tool returns for each entity type: CIK/ticker/LEI/FIGI for companies, RxCUI/ingredient/brand for drugs, ambiguity candidates, and explicit unresolved fields. It also covers input formats and failure modes, giving an agent enough context 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, but the description significantly enriches both parameters. It details accepted inputs for company (ticker, CIK, ISIN, name), specifies drug brand/generic examples, explains ISIN-to-LEI resolution, and gives a critical bond-naming caution. This substantially aids correct invocation.

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

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

The description explicitly states that the tool resolves a user-spoken name to canonical/official identifiers (CIK, LEI, FIGI, RxCUI) needed by other tools. It enumerates supported types and gives concrete examples like tickers, bonds, and drug names, making its purpose unmistakable and distinguishable from siblings.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID,' and provides numerous natural-language trigger examples. It also warns against passing full noun phrases for bonds, but it does not directly contrast with-related tools like entity_profile or compare_entities.

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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is fully declared. The description adds that it fetches from a specific URL, which is useful but minimal extra context beyond annotations.

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

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

The description is two short sentences, no wasted words, and immediately conveys the tool's action and 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 parameterless sample fetch tool with an output schema, the description provides sufficient information: the exact URL and two use cases. No further context is needed.

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

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

There are no parameters, and the schema has 100% coverage (empty). Baseline is 4 for zero-parameter tools. The description does not need to add parameter details.

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

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

The description explicitly states it fetches a sample robots.txt from httpbin.org, and provides two specific use cases: testing robots.txt parsing or as a placeholder. This clearly distinguishes it from sibling tools like 'get' or 'post'.

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 clear context on when to use this tool (testing parsing or placeholder), but does not mention when not to use or alternatives. However, the purpose is so specific that it is not ambiguous.

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, openWorld, idempotent, non-destructive. The description adds that it internally calls ai_visibility_check on each entity and returns a ranked list with score, confidence, signal density. This provides behavioral context beyond the annotations without contradiction.

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

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

Two concise sentences front-load the main purpose, followed by a third summarizing output. No redundant or extraneous words.

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

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

Despite lacking an output schema, the description specifies the return structure (ranked list with score, confidence, signal density per entity). It also clarifies the tool's dependence on ai_visibility_check. For a tool with 4 parameters and annotations, this is complete.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning by stating the first entity is treated as 'subject' for narrative and that omitting models defaults to workers-ai. This goes beyond the schema's field 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 uses specific verbs like 'compare', 'probes', 'ranks', and 'surfaces' to describe action on the resource 'AI visibility across multiple entities'. It clearly distinguishes from siblings like ai_visibility_check (single entity) by emphasizing side-by-side comparison.

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

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

The description states it is 'useful for competitive AI-marketing audits' and implies comparison of multiple entities, suggesting when to use. However, it does not explicitly state when not to use or name alternatives (e.g., ai_visibility_check for single entities), though the context from sibling tools makes it clear.

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

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

The description adds significant behavioral context beyond annotations: partial failure handling, bundlephobia timing (5-30s first measurement), and sources_failed reporting. No contradictions with annotations (readOnlyHint, etc.).

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 key purpose and use cases but is somewhat verbose. Every sentence is useful, but could be tightened slightly. Overall well-structured.

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

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

Given no output schema, the description comprehensively explains return value structure (summary block, per-advisory detail, links, alternative versions) and failure modes (sources_failed). Covers all necessary aspects for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the description adds nuance: scoped packages accepted, version defaults to latest. While schema documents parameters, the description provides practical usage context.

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

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

The description clearly defines the tool as a composite check for npm packages covering license, advisories, version history, and bundle size. It distinguishes itself from sibling tools by focusing specifically on npm dependency scanning, with a clear verb-resource structure.

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 the agent asks about safety, popularity, size, or cost of adding a package. Also clarifies NPM-only scope in v1 and directs to alternative deps.dev:version for other ecosystems, providing clear 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, idempotentHint, etc. The description adds behavioral details: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flag, and return of offsets. No contradictions.

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

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

Two concise sentences that are dense with information. Front-loaded with the core purpose, then specifics. 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?

Despite no output schema, the description explains return values (passages with offsets and similarity scores), covers embedding/chunking details, and addresses input limits. Fully adequate 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 coverage is 100% with descriptions for all parameters. The description enhances these by providing query examples and clarifying the truncation behavior for text. Adds value beyond the schema.

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

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

The description opens with 'Semantic search INSIDE a fetched record', clearly stating the verb (search) and resource (a fetched record). It distinguishes itself from siblings by noting it pairs with ask_pipeworx_grounded, making its role unique.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt — search_within saves context...' and mentions it pairs with ask_pipeworx_grounded. This provides clear when-to-use and alternative 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 non-destructive behavior, so the safety profile is clear. The description adds no further behavioral details (e.g., whether it makes network calls or performs a lookup), but it does not contradict annotations either.

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 extremely concise (6 words), which is appropriate for a simple tool. However, it sacrifices informativeness for brevity; a slightly longer description could include parameter behavior or output format without losing conciseness.

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

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

Given the tool has one parameter, no schema description coverage, and an output schema exists, the description should at least mention what the output contains. Without that, the agent lacks key information to interpret the tool's response, making the description incomplete.

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 0% schema description coverage, the description must compensate for the undocumented 'code' parameter. It only states 'given HTTP status', implying that 'code' is an HTTP status number, but fails to specify valid ranges, format, or examples. This minimal guidance leaves the agent to guess parameter semantics.

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

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

The description 'Return given HTTP status' uses a clear verb ('Return') and resource ('HTTP status'). It distinguishes the tool from siblings like 'get' and 'post' which involve actual HTTP requests. However, it lacks detail on what exactly is returned (e.g., status text, full response object), which reduces specificity.

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?

There is no guidance on when to use this tool versus alternatives. For example, when should an agent use 'status' instead of 'get' to check a URL's response? The description offers no contextual cues for tool selection.

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

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

The description discloses important behavioral traits not fully covered by annotations, such as the requirement for a verified phone and SMS cap for SMS delivery, and webhook signing details. It does not contradict the annotations, though the idempotent hint is not explicitly addressed.

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

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

The description is a single paragraph but front-loads the core purpose. It is relatively concise given the complexity, though it could be better structured with bullet points for readability.

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

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

The description covers the return value, prerequisites, supported types with examples, delivery options with constraints, and security details. It is complete for a tool 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?

With 100% schema coverage, the description adds significant meaning beyond the schema by providing concrete examples for each subscription type and extra constraints for delivery parameters (e.g., phone verification, daily cap).

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

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

The description clearly states the verb 'Create' and the resource 'proactive monitoring subscription', distinguishing it from sibling tools like 'unsubscribe' and 'list_subscriptions'. It provides specific examples of supported types and delivery channels.

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

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

The description includes context for usage (requires Pipeworx OAuth account), supported types, and delivery channels. However, it lacks explicit guidance on when not to use this tool versus alternatives like 'polymarket_arbitrage' or 'polymarket_edge_tracker'.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds value by explaining that the tool returns category-bucketed example questions with exact tool and argument shape from a live catalog. It does not contradict annotations.

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

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

The description is fairly concise given the amount of information conveyed. It front-loads alternative phrasings and then clearly states purpose, output, and usage. Some redundancy exists (e.g., listing categories), but overall it is well-structured.

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

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

With no output schema, the description adequately explains the return format: category-bucketed example questions with tool and argument shape. It also covers when to use the tool, the optional parameter behavior, and the full set of categories. This 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 coverage is 100%, with the schema providing a description for the optional topic parameter. The description repeats this information and adds usage context about full spread vs. focus, but does not add substantial new semantics beyond the schema.

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

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

The description clearly states the tool's purpose as the onboarding entry point for an agent to learn what questions to ask Pipeworx. It specifies the verb 'suggest questions' and distinguishes from sibling tools like ask_pipeworx by focusing on example queries rather than answering them.

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 instructions are given: '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 when to pass the topic argument vs. omit it, providing clear context for when to use this tool over 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 provide idempotentHint and destructiveHint. The description adds value by specifying ownership enforcement, that the row is deactivated (not deleted), and that historical events remain via recent_alerts. 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 short sentences with no waste. The first sentence states the action, the second adds ownership, the third explains the deactivation behavior. Efficient and front-loaded.

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, the description covers all necessary information: action, ownership, persistence model, and link to recent_alerts. Complete for agent decision-making.

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

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

Schema coverage is 100%; the parameter 'id' is described as a UUID from subscribe. The description does not add additional meaning beyond the schema, 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 'Cancel a subscription by id' with specific verb and resource. It distinguishes from siblings by mentioning ownership enforcement and deactivation behavior, setting it apart from 'subscribe' and 'list_subscriptions'.

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

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

The description gives clear context for when to use the tool (to cancel a subscription) and includes an important ownership constraint. However, it does not explicitly mention alternatives or when not to use it, though the purpose is straightforward.

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 does not add any behavioral traits beyond the annotations, which already indicate readOnly, idempotent, and non-destructive. No additional context is given.

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

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

The description is extremely concise (two words) but lacks structure and sufficient meaning. It earns its place but could be more informative.

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 simplicity of the tool (no parameters, output schema exists), the description is overly minimal. It does not clarify what the tool returns or how to interpret the result, leaving gaps for agent understanding.

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

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

There are zero parameters, and the schema coverage is 100% (vacuously). According to the baseline rule for 0 params, score is 4.

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

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

The description 'Caller User-Agent' indicates that the tool returns the user agent of the caller, but it uses a noun phrase rather than a verb, making the action implicit. It is vague but not a tautology.

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?

No guidance is provided on when to use this tool or how it compares to siblings. The description lacks context 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description carries low burden. It adds no behavioral details beyond the fact that it returns a random UUID, which is consistent 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 words long, immediately front-loaded with the core purpose. Every word earns its place with zero 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 zero-parameter tool with an output schema, the description conveys exactly what the tool does. No additional information is necessary for correct invocation.

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

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

Tool has zero parameters, so schema coverage is 100%. Description 'Random UUID' succinctly conveys what the tool outputs. Baseline for 0 parameters is 4, and description is adequate.

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

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

Description 'Random UUID.' explicitly states the tool generates a random UUID, which is a specific verb+resource. It is clear and distinguishable from sibling tools, none of which are UUID-related.

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?

No guidance on when to use this tool versus alternatives. The description provides no context for decision-making, such as when UUID generation is appropriate.

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

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

The description adds significant behavioral context beyond the annotations: verdict semantics, the critical distinction that 'could_not_verify' indicates a failed check and must not be used as evidence, and that 'unsupported' means no source was found. It also discloses internal routing and error object structure. This complements the readOnly/openWorld/idempotent hints without contradicting them.

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

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

The description is long but densely packed—every sentence carries operational value: example intents, usage rule, pipeline paths, return details, error warnings, and efficiency rationale. It is well structured in three paragraphs and not redundant, though it could be slightly more concise by trimming technical specifics like 'percent-delta math'.

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 compensates by fully enumerating the verdict enum, the returned citation, reasoning, and error handling details. It also covers the two routing pipelines and explains edge cases (could_not_verify vs unsupported). For a tool of this complexity, the description is complete enough for an agent to invoke and interpret results correctly.

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

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

Schema description coverage is 100%, so both parameters ('claim' and 'tolerance_pct') are already well-documented with examples and detailed semantics. The tool description adds no extra parameter meaning beyond the schema, 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 uses a specific verb+resource: 'natural-language claim verification against authoritative sources.' It distinguishes the tool from siblings by focusing on fact-checking intents and mentions a consolidated pipeline that replaces 4–6 sequential calls. The examples of user phrasings make the purpose immediately recognizable.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' and clarifies the scope by distinguishing company-financial claims (SEC EDGAR fast path) from all other factual claims (grounded pipeline). This gives clear when-to-use guidance, and the 'Replaces 4–6 sequential calls' note explains why this tool is preferable to multi-step 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 readOnlyHint, idempotentHint, and non-destructive. Description adds the source (httpbin.org/xml) and use cases, providing useful behavioral context beyond annotations without contradiction.

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

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

Two sentences, zero wasted words. Front-loaded with action and resource, then use cases. Highly efficient.

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

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

Given no parameters, presence of output schema (covers return value), and annotations covering safety, the description fully covers purpose, usage, and behavior. Complete for this simple 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?

No parameters; schema coverage is 100% (since none exist). Per guidelines, baseline is 4 for 0 parameters. Description adds nothing about parameters because there are none.

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

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

Description clearly states it fetches a sample XML response from httpbin.org, with specific verb ('Fetch') and resource ('sample XML response'). Distinguishes from siblings like json_anything or html_anything by explicitly mentioning XML content-type handling.

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

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

Explicitly says when to use: to verify XML content-type handling or as a placeholder in tests. No exclusions or alternatives mentioned, but given the tool's simplicity and that siblings cover similar cases for other formats, it provides adequate context.

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