pokemon

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable behavioral context: passing `_apiKey` triggers calls to Anthropic with the user paying directly, and the default model is free (Workers AI Llama-3.3-70b). It also discloses the return shape, which is not covered by annotations. This goes well beyond the annotation hints.

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

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

The description is four sentences, each serving a distinct purpose: main functionality, defaults and API key usage, return format, and typical use cases. It is front-loaded with the primary action and contains no filler. Every sentence earns its place.

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

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

Since there is no output schema, the description explicitly lists the per-model return fields (score, confidence, signals, raw_response) and the combined view. It also covers cost implications, default model, and use cases, which is complete for a tool with only four parameters and no nested objects. The description gives enough context for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100%, so parameters are already well-documented. The description adds meaning by explaining the cost implication of `_apiKey`, the default model behavior, and that the models array is optional. It reinforces the `entity` parameter and clarifies the optionality of `models`, complementing 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 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model', specifying both the action and resource. It uses a specific verb ('probe') and differentiates from siblings like scan_competitor_ai_presence by focusing on general entity visibility scoring. This is a specific, unambiguous purpose.

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

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

The description gives clear context for when to use the tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains parameter usage, such as passing `_apiKey` to also probe Anthropic and the default model. It doesn't explicitly name alternative tools or state when not to use it, but the context is sufficient for most 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?

The description adds behavior beyond annotations: it routes to many tools, returns stable citation URIs, works on every tier, and is a fast single call. It also indicates it covers news feeds. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description does not contradict them. It does not mention rate limits or error handling, but the added context is valuable.

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 and front-loaded with the key directive ('PREFER OVER WEB SEARCH'). It includes examples and alternatives in a logical flow. While it could be trimmed, every sentence carries useful guidance for a broad routing tool, so it earns its length without being redundant.

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

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

Given the tool's complexity (a router to thousands of sources) and lack of output schema, the description is complete: it covers what it does, when to use it, when to step up to alternatives, example queries, return format (structured answer with citations), and operational notes (fast, works on every tier). Nothing critical is missing for an agent to use it correctly.

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

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

Schema description coverage is 100% for all 6 parameters, so the schema already documents them well. The description provides example queries but does not add semantic detail beyond spelling out that any alias (q, text, input, query, prompt) works. Since coverage is high, the baseline of 3 is appropriate; there is no additional parameter semantics needed.

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

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

The description clearly states the tool's purpose: answering factual questions about real-world data, listing many domains (SEC, FDA, FRED/BLS, etc.). It explicitly says it routes to '5,635 tools across 1477 verified sources' and returns structured answers with citations. It distinguishes from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for different needs.

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

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

It gives explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE for most questions', trigger phrases like 'what is', 'look up') and when-not-to-use ('Step up only when needed' for hallucination-resistant answers or broad multi-part questions). It names the alternative tools (ask_pipeworx_grounded, deep_research) and explains the conditions to choose them.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, so the description does not need to repeat those. It adds valuable context about the beta nature (live candidate testing, current inactivity, and that it is a fully working router with no fallback). This exceeds baseline expectations without contradicting annotations.

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

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

The description is moderately long but each sentence carries essential information: purpose, current state, usage instruction, and the fact that it's a full router. It front-loads the core identity and clearly signals the beta status. While it could be slightly tightened, it is well-structured and not redundant.

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 5,635 tools, the description adequately covers the purpose, current behavior, and relationship to the stable ask_pipeworx. It references the stable tool for response shape and usage, which is sufficient given the sibling context. No critical missing information that an agent needs to call it correctly.

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

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

With 100% schema description coverage, the schema already documents all six parameters and their aliases thoroughly. The description only mentions 'same arguments' and doesn't add semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx with an identical universal routing function. It states the resource (5,635 tools), arguments, and response shape, and explicitly differentiates it from the stable sibling by mentioning experimental routing improvements and the current state (no active candidate, matches ask_pipeworx 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?

It gives an explicit directive to 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router for merge decisions. It also clarifies the current behavior (matches stable) and warns it is the experimental edge, making when-to-use versus alternatives clear.

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

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

Annotations already include readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context: the refusal mechanism, potential refusal reasons, the extra LLM call cost, and the guarantee of evidence with verbatim quotes. It fully discloses the tool's behavior without any 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 sentence earns its place. It front-loads the key differentiator (hallucination-resistant), then systematically covers routing, extraction behavior, return format, usage conditions, and cost tradeoff. No redundancy or filler.

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

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

For a tool with no output schema, the description thoroughly covers return structure, refusal reasons, and usage contexts. It also addresses cost implications and comparison with a sibling. An agent has all the information needed to decide when to use it and what to expect from the response.

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

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

Schema description coverage is 100%, and every parameter is an alias for 'question'. The description does not add any new parameter semantics beyond what the schema provides; it only mentions the return format. This is the baseline score for high coverage with no additional param 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 states a specific purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly differentiates from the sibling ask_pipeworx by explaining it uses the same routing but extracts the answer strictly from tool results. The verb 'answer' and resource 'Pipeworx' are explicit, and the contrast with the sibling is actionable.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' with concrete examples (financial verdicts, legal claims, medical lookups, public statements). Also gives a clear when-not-to-use: 'prefer ask_pipeworx for casual lookups' and explains the cost tradeoff. This is exemplary.

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, non-destructive. The description adds substantial behavioral detail: low-confidence matches short-circuit with status, closed markets return status, wide-spread markers, cancellation rule parsing, news fallback indicators, and a warning about flat-50¢ void settlements. 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?

Long but appropriately sized for a complex tool with many behaviors. Structured into labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) with front-loaded purpose. No redundant sentences; every section adds unique information. For its complexity, this is exemplary.

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 documents the full response contract: result.market fields, result.analysis edge warnings, result.evidence keying, resolver match confidence, parent_event legs, news fallback fields, and safety statuses. It covers edge cases (closed markets, illiquid spreads, cancellation rules) thoroughly. 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?

Schema covers 100% of parameters with descriptions. The description adds semantic context: market parameter accepts slug/URL/question text, depth controls fan-out count, include_raw controls response size. It also ties parameters to output shapes (quick vs thorough). Baseline 3 is elevated to 4 because the description explains how parameter choices affect behavior and response structure.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clarifies the market resolution, classification, fan-out to data packs, and returns an evidence packet + comparison. This distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on single-bet research with 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?

Explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It also provides example query formulations. However, it doesn't explicitly contrast with sibling tools or state when not to use, so it misses the full when/not-when/alternatives spec.

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

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

Annotations already declare read-only, open-world, and idempotent hints. The description adds valuable behavior: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradiction with annotations; it enriches 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 dense but every sentence adds value: triggers, entity count, preference rule, data specifics, sorting behavior, and output format. It's front-loaded with natural language examples and avoids filler.

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

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

Given no output schema, the description covers return values ('paired data + pipeworx:// citation URIs per entity') and behavioral details. It thoroughly explains what happens with different types and edge cases (off-calendar fiscal years), making the tool fully usable without external documentation.

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

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

Schema covers 100% of parameter descriptions. The description adds semantics by explaining what each type ('company' vs 'drug') pulls and clarifies value formats (tickers/CIKs vs drug names). This goes beyond the schema's generic 'entity type' and 'names' 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 and scope: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It clearly distinguishes from sequential single-pack lookups and lists concrete trigger phrases. This separates it from siblings like entity_profile.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides trigger examples. This gives clear when-to-use guidance, though it doesn't state when not to use it, the strong preference and examples are sufficient.

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 (readOnlyHint, openWorldHint, idempotentHint) are provided, and the description adds substantial context beyond them: gap recovery behavior, contradictions[] scan, hop field, citation_uri fetchability guarantee, semantic excerpting, latency expectations (15-60s, thorough up to ~90s), and the paid-tier gate for depth:"thorough". No contradiction with annotations — readOnlyHint aligns with the 'never invented' grounded claim.

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

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

The description is long but every sentence earns its place — auth gate, domain scope, decomposition behavior, output packet structure, and alternative tools. The critical account requirement is front-loaded. It sits near the upper limit of acceptable length, but the complexity (two alternatives, depth ladder, multi-hop semantics) justifies the density without bloat.

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 present, the description properly explains the return value: findings packet with verbatim evidence + confidence + source + fetched_at + stable pipeworx:// citation, explicit gaps[], and contradictions[]. It accounts for the auth tier, cache/latency expectations, and second-hop iteration. An agent has everything needed to call it correctly and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds behavioral meaning beyond the schema by explaining what each depth level produces (standard = gap-recovery hop + contradictions scan; thorough = full iterative chase), plus the auth constraint that thorough requires a paid plan — nuance not present in the schema enum descriptions.

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

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

The description states a specific verb+resource ('Grounded multi-source research across Pipeworx's 1477 STRUCTURED data sources') and explicitly differentiates from open-web search and from siblings like ask_pipeworx ('it routes to live news APIs'). An agent can immediately distinguish this from the sibling research tools and understand its structured-data domain.

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 ('Best for broad/multi-part questions over structured data') and when-not-to-use guidance with named alternatives ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS...prefer ask_pipeworx'). It also states the default and fallback path for unauthenticated users ('If you are not signed in, use ask_pipeworx instead'). Nothing is left to inference.

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

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

The annotations already declare readOnlyHint=true and idempotentHint=true. The description adds behavioral depth by explaining the output format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and 'ready to call directly, no second schema lookup needed.' This goes beyond the annotations' safety profile.

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

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

The description is a single paragraph that front-loads the core purpose ('Find tools by describing the data or task') before listing domains, return behavior, and a usage directive. While the domain list is extensive, each sentence contributes useful context and the description remains focused without redundancy.

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

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

The description covers when to use the tool, what it returns, and the structure of results, while the schema provides rich examples for the query parameter. It lacks details on edge cases like zero matches, but for a read-only discovery tool with no output schema, this level of completeness is sufficient.

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

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

Schema description coverage is 100%, with 'query' and its aliases fully documented along with examples. The description reinforces the query concept ('describing the data or task') but does not add new parameter-level semantics beyond what the schema already provides. 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 opens with a specific verb and resource: 'Find tools by describing the data or task.' It clearly differentiates itself from sibling tools by positioning as a discovery meta-tool: 'Call this FIRST... to see the option set (not just one answer).' This distinguishes it from direct-answer or search 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?

Explicit usage context is provided: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' This gives clear when-to-use guidance, though it stops short of explicitly naming alternatives or stating when-not-to-use conditions.

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 rich behavioral detail beyond the annotations: it fans out across multiple sources, returns up to 5 recent filings with specific URIs, sorts fundamentals by period_end DESC, and notes the USPTO API sunset with a soft-fail behavior. It also clarifies input prerequisites (zero-padded CIK). These details add significant value beyond the basic readOnly/idempotent hints.

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

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

The description is dense but organized: starts with high-impact example queries, then purpose, then trade-off guidance, then return structure, then input constraints. It earns its length given the tool's complexity, though the list of eight example phrases could be trimmed slightly without losing meaning. Overall, 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?

Despite having no output schema, the description fully covers what this complex, multi-source tool returns (CIK, filings, fundamentals, patents, news, LEI) including formats and caveats. It also covers limitations (name unsupported, USPTO sunset) and fallback behavior (GDELT→GNews). For a tool with this many moving parts, the description is remarkably complete.

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

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

The schema already covers both parameters with descriptions, giving a baseline of 3. The description adds extra semantic value by explaining the value parameter can be a ticker OR a zero-padded CIK, providing an example, and explicitly instructing to use resolve_entity for names. This elaboration goes beyond the schema's 'ticker or CIK' 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 states the tool builds a 'full cross-source profile of a US public company in ONE parallel call,' listing specific sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and return payload. This distinguishes it from siblings like resolve_entity (which matches names) and compare_entities (which compares). The example queries also make the purpose immediately understandable.

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 when the user asks for a holistic view,' giving clear when-to-use guidance. It also states the alternative: 'names not supported (use resolve_entity first if you only have a name),' naming a specific sibling tool. This is exemplary usage guidance.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds context about use cases (stale context, sensitive data) but does not introduce additional behavioral specifics beyond annotations. No contradiction exists.

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

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

Three concise sentences, front-loaded with the action, followed by targeted usage guidance and sibling references. Every sentence earns its place; no fluff.

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

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

For a simple one-parameter deletion tool with rich annotations and full schema coverage, the description covers purpose, when to use, and related tools. It is complete for the tool's complexity.

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

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

Schema description coverage is 100%: the 'key' parameter is described as 'Memory key to delete.' The tool description only reuses 'by key,' adding no new semantic detail. Baseline 3 applies when schema already documents parameters fully.

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 states 'Delete a previously stored memory by key' with a specific verb and resource, making its purpose immediately clear. It distinguishes itself from siblings like remember and recall by explicitly focusing on 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?

Explicitly provides when-to-use guidance: 'when context is stale, the task is done, or you want to clear sensitive data.' Also mentions pairing with remember and recall, signaling related tools and alternatives.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable process details (fetches page, extracts title/description/key links) and output format (single text blob), going beyond what annotations provide. No contradictions found.

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

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

Four sentences, each earns its place: purpose, process, output format, and use cases. No jargon, no filler, well-structured for quick comprehension.

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

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

Even without an output schema, the description explains the output format ('single text blob ready to drop at site-root/llms.txt'), the process, and the use cases. For a simple read-only tool with well-documented params, 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?

Both parameters are fully described in the schema (100% coverage), so the description doesn't need to add much. It implicitly references the URL parameter ('any URL') but adds no extra syntax or behavior beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's action ('Generate a production-ready llms.txt file'), the input ('any URL'), and the purpose (AI crawlers indexing). It distinguishes itself from sibling tools by focusing on the specific llms.txt output format, 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?

Provides concrete use cases: getting client sites indexed, drafting llms.txt, and auditing competitors. While it does not explicitly mention alternatives or when not to use, the context is clear and sufficient for an agent to choose this tool for llms.txt generation.

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 the tool read-only, idempotent, and non-destructive. The description adds value by specifying the output content ('effect description and all Pokémon that can have this ability') and giving concrete examples. No contradictions with annotations. The description provides useful behavioral detail beyond the structured metadata.

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

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

The description is one sentence, front-loaded with the action and resource, and includes examples plus return summary. Every word is informative; there is no redundant or extraneous 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?

This is a simple tool with one parameter, full schema coverage, rich annotations, and an existing output schema. The description fully covers the purpose and return behavior, making it complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100% for the single 'ability' parameter, with the schema already including a description and examples. The tool description repeats the examples but adds no new semantic information beyond what the schema provides. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Look up a Pokémon ability' with examples ('static', 'overgrow') and specifies the return value ('effect description and all Pokémon that can have this ability'). It clearly distinguishes itself from sibling tools like get_pokemon and get_type by focusing specifically on abilities.

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

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

The description provides clear context that this tool is for looking up Pokémon abilities, which implies when to use it. However, it does not mention alternatives or explicitly state when not to use it. Thus it meets the 'clear context, no exclusions' level.

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 description doesn't need to cover safety. It adds value by disclosing the return payload details (stages, triggers, levels, items), which are beyond the annotations. No contradictions exist.

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, compact sentence that front-loads the action ('Trace a full evolution line') and then lists key return elements. Every clause earns its place with 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?

With an output schema present and annotations covering safety, the description fully specifies what the tool does and what it returns. The simple one-parameter interface and straightforward purpose mean no additional context is necessary.

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

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

The schema description for 'id' provides full coverage (100%) with examples (1 for Bulbasaur, 10 for Caterpie). The tool description's mention of 'chain ID' is redundant with the schema, adding no new parameter semantics. Baseline of 3 is appropriate.

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

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

The description clearly states a specific verb ('trace'), a resource ('full evolution line'), and the lookup method ('by chain ID'), distinguishing it from sibling tools like get_pokemon or get_type. The mention of returning stages with triggers, level requirements, and items leaves no ambiguity about its function.

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

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

While it doesn't explicitly name alternative tools or exclusion conditions, the description strongly implies use when needing an evolution chain by ID. The context is clear and distinct from siblings, but lacks explicit when-not or alternative guidance, keeping it a step below the highest bar.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, non-destructive operation. The description adds the specific data categories returned and the name/ID lookup, providing some context, but it does not disclose potential errors, rate limits, or any edge cases. Thus it adds only moderate value beyond the annotations.

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

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

The description is two sentences: the first clearly states the tool's purpose and the second explains the lookup method. It is front-loaded, concise, and contains no filler or repeated information from the schema.

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

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

This is a simple, single-parameter lookup tool with a rich output schema and comprehensive annotations. The description covers its purpose and usage adequately; because an output schema exists, there is no need to describe return values. It is complete for its complexity.

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

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

The input schema has 100% coverage and already describes the 'name' parameter as accepting a Pokémon name or numeric ID, with examples. The description repeats this same information without adding any new semantic details, so it does not compensate or expand beyond the schema. A baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Get') and resource ('a Pokémon') while enumerating the exact data returned (stats, types, abilities, height, weight, sprites). It also states the dual lookup method (name or ID), which clearly differentiates it from sibling tools like get_ability, get_type, or get_evolution_chain that target specific sub-resources.

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

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

The description implies the tool is for retrieving core Pokémon information but does not explicitly say when to use it over alternatives or when not to use it. It mentions the lookup methods but gives no exclusions or comparisons with related tools, leaving selection partially to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the description adds value by disclosing the return behavior: 'Returns damage chart and up to 20 Pokémon.' It also implies a search/filter behavior (finding by type) and states an output limit, which are useful beyond the annotation's safety hints.

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

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

The description is two sentences, front-loaded with the core purpose and followed by return details. Every word contributes value: it explains the type context, the output (damage chart), and the result limit. No filler or redundancy.

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

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

For a tool with one well-documented parameter, an output schema, and comprehensive annotations (readOnly, idempotent, non-destructive), this description is complete. It tells the agent what the tool does, what it returns, and implies the search scope. There are no critical gaps given the tool's simplicity.

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

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

Schema description coverage is 100%, and the parameter is already well-defined in the schema with examples ('fire', 'water'). The description repeats these examples but does not add additional meaning (e.g., valid values, formatting) beyond what the schema provides. 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 and resource: 'Check type effectiveness matchups and find Pokémon by type'. It clearly distinguishes from siblings like get_pokemon (specific Pokémon) and get_ability (ability info) by focusing on type-based queries and matchups. The added detail about returning a damage chart and up to 20 Pokémon further clarifies its purpose.

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

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

The description provides clear context for when to use the tool: when you need type effectiveness matchups or want to find Pokémon by type. It does not explicitly name alternatives or exclusions, but the sibling list includes related tools (get_pokemon, get_ability) and the description's specificity makes the intended use clear without needing explicit 'when-not' statements.

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 and destructiveHint false. The description adds the exact return fields (id, type, params, created_at, last_fired_at, fire_count), which is valuable since there is no output schema. No contradictions with annotations.

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

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

The description is three sentences, each serving a purpose: stating the action, listing return fields, and giving usage guidance. No fluff or redundant content.

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

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

For a simple list tool with one optional parameter and no output schema, the description provides the action, return fields, and usage guidance. It could mention potential absence of results or ordering, but the essential context is present.

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

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

The schema covers 100% of the parameter 'include_inactive' with a clear description. The tool description does not add further parameter details, but the baseline of 3 is appropriate given full schema coverage.

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

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

The description states 'List the caller's active subscriptions' with a clear verb and resource. It also differentiates from sibling tools by specifying the caller's own active subscriptions and mentions use cases related to subscribe and unsubscribe.

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

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

The description explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel,' providing clear context for when to use it relative to subscribing and unsubscribing.

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?

While annotations are all false (neutral), the description adds substantial behavioral context: filing without an account returns a claim_token, later passing it back reads resolution status, rate limit is 5/day, free/no quota impact, and the team reads digests daily. 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?

Dense but every sentence carries distinct information: purpose, exclusions, claim_token mechanics, rate limit, quota, and roadmap signal. It front-loads the core purpose and remains appropriately sized for a tool with nuanced usage rules.

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

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

No output schema exists, so the description correctly explains return behavior via claim_token and later status reads. It covers exclusions, limits, structured context, and follow-up usage, making it complete for a feedback tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful value by explaining the claim_token round-trip flow, emphasizing message specificity, and reinforcing the type enum categories. This lifts it above schema-only.

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

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

The description opens with a specific verb-object ('Tell the Pipeworx team something is broken, missing, or needs to exist') and clearly identifies this as feedback for Pipeworx tools. It distinguishes itself from data-retrieval siblings like ask_pipeworx or pipeworx_trending by focusing on reporting issues/praise about the tool catalog itself.

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 enumerates when to use (bug, feature/data_gap, praise) and when NOT to use (issues with another vendor's MCP server), even naming the alternative action ('file it with that server instead'). It also clarifies scope with '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?

Beyond the readOnly/idempotent annotations, the description adds useful behavioral context: derived from CF analytics-engine, no PII, returns only (pack, tool, count), and cached 5min-1h depending on window. This helps agents understand data freshness and privacy boundaries.

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 front-loaded with the core purpose, uses compact bullet-style use cases, and every sentence adds value—including caching and data-source details. Structured for quick scanning.

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

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

With one optional parameter and no output schema, the description fully specifies the return content (top tools, top packs, total call volume, and tuple format) and adds context about aggregation and privacy, 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 schema already covers the single window parameter at 100% with semantics ('Shorter windows surface what's hot right now...'). The tool-level description mostly repeats that, adding no new parameter meaning, 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?

States clearly it returns top tools, top packs, and total call volume over a recent window, with a specific subject (what other AI agents are calling on Pipeworx). This distinguishes it from sibling tools like discover_tools by focusing on aggregate usage trends rather than discovery.

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

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

Provides explicit 'Useful for' scenarios and window-selection guidance ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). However, it does not explicitly mention when not to use it or name alternatives like discover_tools.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description discloses the fill check warning: 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it.' It also explains filters like placeholder slugs and Jaccard similarity, providing substantial behavioral context without contradicting annotations.

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

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

The description is long but well-structured with bolded section headers and concise clauses. Almost every sentence adds value, though a few technical details could be tightened. Still, given the tool's complexity, the length is justified and front-loaded with the core purpose.

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

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

The description fully explains return shapes: 'Response: opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context), and in event mode partition_check{...}.' It also covers edge cases (placeholders, thin legs, fill check), making it complete for an agent to use 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?

Although schema coverage is 100%, the description adds deep meaning to both params. It explains what a valid event slug looks like, accepts full URLs, clarifies that topic is a seed question, and details the semantic anchor (≥0.30 Jaccard) and partition filter behavior, far exceeding schema descriptions.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly distinguishes it from sibling tools like polymarket_edges or polymarket_fill_risk, and the detail about modes (trending_scan, event, topic) solidifies its unique purpose.

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

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

It explicitly tells when to use each mode: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It even points to an alternative: 'For custom sizing use polymarket_fill_risk.' This is exemplary usage guidance with clear context and exclusions.

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

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

The description goes far beyond the readOnly/openWorld/idempotent hints by disclosing caching behavior ('Cached 1h at the KV level keyed on all knobs'), 24h-move warnings, 'rare-by-design' market construction, diagnostics for empty segments, and the Fed data caveat. This gives agents a robust behavioral model of what to expect beyond the annotations.

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

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

The description is long but dense, with well-labeled sections like 'TRADEABLE-EDGE KNOBS' and 'RESPONSE TOP-LEVEL'. The front-loading works: it opens with the core purpose before diving into model details. It could be slightly more scannable if split into paragraphs, but every sentence carries substantive information.

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

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

With no output schema, the description fully specifies the response shape: top-level by_segment, fed_candidates/fed_note, and _diagnostics with funnel counters. It explains segment composition, per-opportunity fields, how knobs affect output, and even why segments may be empty. This is as complete as one could expect for a complex 9-parameter 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?

Even though schema coverage is 100%, the description enriches the parameters by explaining how they interact with the pipeline (e.g., 'TRADEABLE-EDGE KNOBS: min_liquidity / max_spread_pp drop opportunities where edge isn't realizable') and by contextualizing slippage with Polymarket market microstructure ('bid/ask + thin depth typically eats 20-50bp per trade'). It adds value without repeating 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 opens with a precise verb-resource pair: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further clarifies the use case ('what should I bet on today') and enumerates three distinct model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), distinguishing it from siblings like polymarket_arbitrage and 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 clearly states the intended use case ('discover opportunities without paging hundreds of markets') and provides behavioral boundaries, such as why Fed bets are excluded from ranking ('1m-T vs EFFR signal is unreliable at meeting-month horizons'). However, it does not explicitly name alternative tools for when not to use this tool, so it stops short of a 5.

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

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

The description goes well beyond annotations, disclosing data source details (daily closes of edge_pp_net, not intraday), snapshot TTL limits (60-day, starts when snapshotting enabled), and the meaning of gaps in snapshot_dates. It also explains that decay is computed on absolute edge_pp_net and that the value is signed by trade direction. This is rich behavioral context that matches the readOnlyHint.

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

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

Although long, the description is exceptionally well-structured with clear sections (Args, RESPONSE, LIMITS) and every sentence carries substantive value. It front-loads the purpose and then organizes detailed telemetry output and limits logically. There is no redundancy or wasted space.

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

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

Given the tool's complexity and the absence of an output schema, the description thoroughly explains the return structure (tracked, expired, snapshot_dates) with field-level meanings and caveats. It also covers limitations and interpretation guidance (median lifespan as competition clock). This is complete for an agent to invoke and understand 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 description coverage is 100% since both parameters have descriptions. The description largely repeats the schema's parameter info (days lookback with defaults, window snapshot family), adding only marginal context like 'snapshot family' and 'max 30' which is already in the schema. There is no additional parameter meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It directly answers what the tool does and distinguishes it from likely sibling tools like polymarket_edges by focusing on historical persistence ('how long has this edge existed and is it shrinking?'). The verb 'telemetry' and resource 'edge' are specific.

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

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

The description provides clear context for when to use the tool: for analyzing edge persistence over time, with the example that a fresh wide edge vs. a 3-week-old wide edge are different trades. It implies that for current edge data one would use polymarket_edges, but does not explicitly name alternatives or exclusions. The parameter explanations also guide usage, so this is a clear but not fully explicit guidelines.

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 the description adds valuable behavioral context: it discloses that basket mode returns forced_directional_risk naming legs that may strand you unhedged, and that partial fills can convert an arb into a directional position. It also explains the max_fillable_usd and verdict fields. However, it doesn't explain rate limits or exact response format, but given annotations cover safety, this is sufficient.

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 information-rich, covering purpose, modes, key parameters, outputs, and usage warnings in a single block. While somewhat long, every sentence earns its place, and the front-loaded 'Realizable-vs-theoretical edge check...' immediately conveys the core purpose. The structure uses clear mode labels (SINGLE-MARKET/BASKET) for easy scanning.

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

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

Given the tool's complexity (two modes, 4 parameters, no output schema), the description provides comprehensive coverage: it enumerates all major outputs (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, etc.), explains basket-mode risks, and includes enough behavioral context for an agent to decide if this tool is appropriate. No critical gaps.

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

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

Schema description coverage is 100%, and the description adds meaning beyond the schema by clarifying how size_usd is interpreted differently in single-market vs basket mode (max spend on buys vs settlement notional S). It also explains the default side behavior in basket mode (auto from partition sum), which is not fully detailed in the parameter schema.

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

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

The description states a specific verb ('check') and resource ('realizable-vs-theoretical edge against live CLOB order-book depth'), distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edges by clarifying it evaluates fill feasibility, not just theoretical edge. It clearly differentiates single-market and basket modes with explicit parameters and outputs.

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

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

Provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and explains why (theoretical overround on thin books is not capturable, partial fills convert arb into unhedged directional position). This is stronger than merely implied usage; it names specific alternatives and conditions.

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: it details compatibility_warning conditions, temporal_alignment, skipped_cross_type/subtype counters, and the meaning of matched_pairs=0 scenarios. It also clarifies that spreads are meaningless if temporal_alignment is false, which is not disclosed in the annotations.

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

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

The description is dense and long but uses labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) to organize information. Every sentence carries meaning, though it could be more concise and structured with paragraphs or bullets 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?

With no output schema, the description fully describes the response structure, edge cases, and safety warnings. It covers both modes, example inputs, and explains what each output field means, making the tool's behavior understandable without seeing the actual response.

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

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

The schema already covers all parameters with descriptions, and the description further clarifies the two modes, the exact list of topic shortcuts, and that explicit parameters override mapped ones. It also explains the response fields and safety fields, which the schema does not cover (no output 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 computes a cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools by focusing on cross-venue comparisons, with specific modes (topic shortcuts and explicit tickers) and output 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?

The description explains two usage modes and when the explicit mode is needed, but does not explicitly name alternative tools or exclusion criteria. It does warn that most pre-mapped topics return compatibility warnings and that pre-mapped does not equal tradeable, providing implicit guidance on when not to expect useful spreads.

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

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

The annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description doesn't need to repeat those. It adds valuable context by explaining the scoping mechanism ('anonymous IP, BYO key hash, or account ID') and the ability to list all keys when the key argument is omitted, which goes beyond the annotations.

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

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

The description is three sentences, with the core action front-loaded. Every sentence earns its place: the first states the primary function, the second gives context, and the third explains scoping and related tools. No unnecessary words.

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

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

For a simple read tool with one optional parameter and no output schema, the description is complete. It covers the core action, usage scenarios, scoping, and how it relates to remember and forget. The return behavior is implied by 'Retrieve a value' and 'list all saved keys,' which is sufficient given the tool's simplicity.

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

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

The schema description covers the only parameter ('key') fully, including the omit-to-list-all behavior, so the description adds no new semantic detail about the parameter itself. The examples of what could be stored (ticker, address, notes) are usage context rather than parameter semantics, so a baseline 3 is appropriate given 100% schema coverage.

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

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

The description clearly specifies the verb 'Retrieve' and the resource ('value previously saved via remember' or 'list all saved keys'), which directly states what the tool does. It distinguishes itself from sibling tools by referencing remember and forget, and the examples (ticker, address, research notes) make the purpose tangible.

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

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

It explicitly says when to use this tool ('Use to look up context the agent stored earlier') and provides examples of appropriate scenarios. It also names alternatives: 'Pair with remember to save, forget to delete,' which tells the agent when to use this versus siblings.

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

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

The annotations declare readOnlyHint:true, but the description discloses a mutating side-effect: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This contradicts the read-only annotation, so per rubric this is an annotation contradiction.

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

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

The description is three sentences, front-loaded with the main action, and every sentence adds value: operation, return format, filtering, mark_read, polling/alternative access. No redundancy or fluff.

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

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

With no output schema, the description mentions the payload fields (source, citation_uri, raw event payload). It covers filtering, mark_read, and polling. Minor ambiguity about mark_read/unread_only interaction, but overall sufficient for effective tool 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 coverage is 100%, so baseline is 3. The description adds an example filter value ('sec_8k') and explains the consequence of mark_read ('so the next call only shows newer ones'), which goes beyond the schema's 'Flag the returned events read in the same call.' This adds contextual meaning.

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

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

The description clearly states the tool 'Pull fired events from your subscription feed' with a specific verb and resource, and details what each returned alert carries. This distinguishes it from siblings like list_subscriptions, which list subscriptions rather than fired events.

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 usage context by noting 'Polls work fine' and pointing to an alternative URL for scripts/dashboards, giving a sense of when to use the tool versus external access. However, it doesn't explicitly compare against sibling tools or state 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 indicate safe read-only operation. Description adds valuable context about source fallbacks (GDELT→GNews), rate-limit handling, soft-fail for USPTO, and the PatentsView sunset. It does not contradict annotations, and the extra behavioral detail boosts transparency beyond the baseline.

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 each sentence adds value, covering purpose, sources, fallbacks, parameter syntax, and output shape. It could be trimmed slightly, but the 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?

Given no output schema, the description explains return structure (changes[] grouped by source, total_changes count, citation URIs). It covers source behaviors, fallbacks, and edge cases, making it complete for a tool with this complexity.

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

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

Schema covers all three parameters, but description enriches meaning by explaining `since` shorthand formats, giving typical values, and clarifying `value` accepts ticker or CIK. This goes beyond the schema's basic descriptions.

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

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

The description explicitly states this is a change feed for a company in a specified time window, listing sources (SEC, GDELT/GNews, USPTO). It includes query examples and distinguishes from entity_profile, making the purpose unmistakable.

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

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

Provides clear when-to-use guidance via query examples and explicitly contrasts with entity_profile for static profile needs. Also advises typical monitoring windows ('30d' or '1m') and explains fallback behavior for news sources.

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 idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description adds valuable behavioral context: persistence rules ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours') and scoping ('scoped by your identifier'). It does not mention overwrite behavior for existing keys, but with annotations this is a minor gap.

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

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

The description is compact and front-loaded with the core action. Three sentences cover purpose, usage, persistence, and sibling relationships with no redundant or filler content. Every sentence contributes information.

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

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

For a simple two-parameter tool with no output schema, the description covers the essential aspects: what is stored, when to use it, persistence behavior, and how it relates to recall/forget. It could mention the return value or confirmation, but this is not necessary for a straightforward save operation.

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

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

Schema coverage is 100% and the schema already describes both parameters with examples. The description adds useful semantic context by explaining the key-value pair structure and scoping, though it does not deeply elaborate on value formatting. This goes slightly beyond the baseline given the high schema coverage.

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

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

The description uses the specific verb 'Save' with a clear resource ('data the agent will need to reuse later') and explicitly contrasts with sibling tools 'recall' and 'forget'. It clearly distinguishes this tool as a memory-write operation across conversations or sessions.

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

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

Provides explicit 'Use when' guidance with concrete examples (resolved ticker, target address, user preference, research subject) and names alternatives: 'Pair with recall to retrieve later, forget to delete.' This gives the agent clear direction on when to invoke this tool versus its siblings.

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

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

The description discloses important behavioral traits beyond annotations: it cascades through multiple lookup endpoints, degrades gracefully (if GLEIF or OpenFIGI unavailable, EDGAR identifiers still return), and explicitly returns unresolved identifiers under an 'unresolved' field. These details are not present in the annotations and add significant transparency about the tool's behavior and limitations.

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

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

The description is fairly long but front-loaded with example queries and the 'use FIRST' directive. Every sentence provides value, though some details (e.g., the precise list of identifiers for companies) could be slightly condensed without losing clarity. Still, it is well-organized and 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 two parameters and no output schema, the description adequately explains what the tool returns (identifiers with source labels, unresolved list, etc.). It covers the core behavior, supported types, and edge cases (graceful degradation). A slightly more explicit description of the response structure would make it fully complete, but it is sufficient for an agent to use effectively.

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 coverage is 100%, but the description adds substantial meaning: it provides concrete examples (AAPL, 0000320193, ozempic), explains how ISIN inputs resolve to legal entities via GLEIF, and distinguishes between company and drug parameter usage. This goes far beyond the schema's terse descriptions and helps the agent form correct inputs.

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 resolves user-spoken names to canonical identifiers, listing specific example queries and supported types ('company' and 'drug'). It explicitly distinguishes itself from siblings by saying 'Use FIRST whenever you have a name but need an ID.' This is specific, actionable, and differentiates the tool from alternatives like entity_profile or compare_entities.

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

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

The description gives explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID'). It also implies that the tool replaces multiple manual lookups. However, it does not explicitly state when NOT to use (e.g., if an ID is already known, use entity_profile instead), which would strengthen the 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, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds valuable context beyond annotations: it reveals the tool internally calls ai_visibility_check per entity, ranks results, and returns a structured list with score, confidence, and signal density. This is meaningful behavioral disclosure.

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 plus an illustrative example and a return-value summary. Every sentence earns its place: purpose, mechanism, use case, and expected output. No redundancy or wasted words.

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

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

Despite lacking an output schema, the description discloses the return format (ranked list with score, confidence, signal density). It covers input constraints (entities 2-8, optional models/context/apiKey), provides an example, and explains the tool's behavior. This is complete for a tool of this complexity with strong 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 description coverage is 100%, so the baseline is 3. The description adds extra semantics by explaining that the first entity in 'entities' is treated as the 'subject' for narrative, with the rest as competitors. It also provides a usage example that clarifies how parameters like 'context' are used, going slightly beyond the schema.

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

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

The description uses a specific verb 'Compare' and clearly identifies the resource (AI visibility across multiple entities) and the mechanism (probes each entity with ai_visibility_check, ranks by score). This distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic).

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 usefulness for competitive AI-marketing audits and provides a concrete example. It implies when to use this instead of ai_visibility_check (multi-entity comparison) but does not explicitly exclude alternatives, so it lacks a formal when-not-to-use clause.

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

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

The description goes beyond the readOnlyHint/idempotentHint annotations by disclosing composite fan-out behavior, potential 5-30s latency on first bundlephobia measurement, and graceful degradation via sources_failed. It also explains partial failure behavior, which is valuable operational context not visible in structured data.

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 information-dense and well-structured: it starts with the primary purpose, then gives use cases, output summary, ecosystem scope, and failure behavior. Every sentence contributes valuable detail without redundancy, appropriate for the tool's composite nature.

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 enumerating the exact return fields, including per-advisory details, links, recent versions, and sources_failed. It also addresses timing expectations and edge cases (new version measurements), making the tool's behavior fully transparent.

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 parameters are fully described in the schema. The description adds context about the npm-specific meaning of 'package' and version defaulting, but this mostly mirrors the schema. No additional parameter semantics beyond what the schema already provides.

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

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

The description states a specific verb ('scan') and resource ('dependency') with a clear composite purpose: determining whether to add an npm package to a project. It clearly distinguishes from siblings by specifying it covers license, advisories, version history, and bundle metrics, and explicitly notes the npm-only scope in v1.

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

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

Explicitly provides when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also names the alternative for non-npm ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), giving 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses several behavioral traits: returns character offsets and similarity scores, uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, and caps input at 200K chars with truncation flagging. This adds significant context without contradicting annotations.

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

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

The description is well-organized: it opens with the core purpose, then explains the primary use case, then pairs it with a related tool, and finally gives technical implementation details. Every sentence adds value, and the length is justified by the richness of information.

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

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

Despite lacking an output schema, the description explains the return format (top-N passages with offsets and similarity scores). It also covers edge cases like character limits and truncation, providing a complete picture for a moderately 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%, so the baseline is 3, but the description adds practical context: the 'text' parameter is illustrated with examples (SEC 10-K, article), 'query' is described as natural-language with example phrasings, and 'limit' is referenced as 'top-N passages'. This goes slightly beyond the schema's literal 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 performs semantic search inside a fetched record, with a specific verb ('search') and resource ('within a source'). It distinguishes itself from siblings by emphasizing it operates on already-fetched text, not on external data retrieval, and explicitly contrasts with ask_pipeworx_grounded.

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

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

The description gives explicit guidance on when to use the tool ('when the record is too big to cram into the prompt') and mentions a complementary workflow with ask_pipeworx_grounded. It also implies not to use it for fetching data, only for searching within existing text.

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 readOnly=false, idempotent=true, destructive=false. Description adds meaningful behavioral context: OAuth requirement prevents anonymous/BYO persistence, SMS requires a verified phone and has a 10/day cap, and the feed is always-on. It stops short of explaining idempotent retry behavior, but annotations cover that.

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

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

The description is dense and well-structured: purpose, requirements, types, and delivery channels are clearly separated. It is longer than strictly needed because it recaps some schema examples, but the extra context is actionable and not redundant waste.

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

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

Covers prerequisites, return value (subscription id), and delivery channel behaviors. However, it lists only 3 of the 5 supported types, omitting patent_grant and clinical_trial, which makes the description incomplete as a standalone overview. Webhook details are left to the schema, which is acceptable.

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

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

Schema covers 100% of parameters with detailed descriptions, so baseline is 3. The description adds domain examples for sec_8k, polymarket_edge, and fred_series, but omits patent_grant and clinical_trial despite the label "Supported types". This is a slight inconsistency and does not fully compensate for schema coverage.

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

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

Description clearly states the verb and resource: "Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id." It distinguishes this from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on the creation act and enumerating the supported alert 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?

Provides clear context: requires a Pipeworx OAuth account, explains the always-on feed and how to pull via recent_alerts or GET registry.pipeworx.io/alerts.json, and notes prerequisites for SMS. It does not explicitly state when not to use or name alternatives like list_subscriptions/unsubscribe, but the context is reasonably clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint:false, and the description adds meaningful context beyond these: it returns category-bucketed examples, each with exact tool+argument shape, and is drawn from a live catalog. This gives the agent a clear mental model of what to expect without contradicting the annotations.

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

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

The description is longer than average, but every sentence serves a purpose: it starts with natural-language queries (front-loading), then states the core behavior, then parameter usage, and finally when to use it. It is well-structured but slightly dense, so it doesn't earn a perfect 5 for 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?

For a tool with one optional parameter and no output schema, the description fully explains the return behavior (category-bucketed examples with tool+argument shape), the parameter semantics, and the scenarios for use. It is a complete onboarding resource, so no critical information is missing.

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

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

The schema covers 100% of the parameter (topic) with valid values, and the description adds extra semantic value by explaining that omitting topic yields a cross-category spread and providing example values like 'finance', 'pharma', and 'betting'. This goes beyond the schema's bare enum-like list, though it doesn't add much syntax-level detail.

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 suggest_questions as the onboarding entry point for learning what Pipeworx can do, with a specific verb ('returns category-bucketed example questions') and a concrete resource (live tool catalog). It also distinguishes itself from siblings like discover_tools by framing itself as the first stop for new agents and explicitly naming the meta-tools it can teach.

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

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

Explicit guidance is given: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the no-argument vs. topic-filtered calling convention, fulfilling the 'when' and 'how' criteria at a high level.

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 beyond annotations: ownership enforcement, deactivation instead of deletion, and that historical events remain accessible via recent_alerts. This adds significant context that annotations (readOnlyHint false, destructiveHint false, idempotentHint true) do not capture.

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

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

The description is two sentences, front-loaded with the action, and every sentence adds value. It is concise with no filler or repetition.

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

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

For a low-complexity tool with one parameter and no output schema, the description fully covers the necessary context: what happens to the row, ownership rules, and the availability of historical events. It is complete enough 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% with a clear description of 'id' as a subscription UUID returned by subscribe. The description adds extra meaning by noting that only your own subscriptions can be canceled, which clarifies the id parameter's ownership constraint. This goes beyond the schema.

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

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

The description states a specific verb and resource: 'Cancel a subscription by id.' It clearly differentiates from siblings like subscribe and list_subscriptions by indicating the inverse operation. The ownership enforcement adds another distinguishing detail.

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

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

The description provides clear context about when to use this tool (for canceling subscriptions) and adds constraints like ownership enforcement. It does not explicitly name alternatives, but the mention that historical events stay available via recent_alerts implies a related alternative for viewing history. No explicit exclusions, but context is sufficient.

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

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

Annotations already declare read-only, idempotent, and open-world behavior, so the bar is lower, but the description adds significant behavioral nuance beyond annotations: the crucial distinction between 'could_not_verify' (check did not happen, not evidence) and 'unsupported' (no source found), plus the structured vs. grounded routing logic. This is exactly the kind of contextual disclosure that prevents misuse.

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 (around 150 words) but every sentence carries valuable information: query examples, usage trigger, routing logic, return structure, and critical caller warnings. It is front-loaded with examples and the 'Use whenever' statement. Slightly verbose but justified by the tool's complexity; could be tightened by removing redundancy (e.g., 'grounded pipeline' repeated).

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 high complexity (two pipelines, six verdicts, no output schema), the description covers the critical aspects: return format, citation, verdict list, and the most dangerous misinterpretation (could_not_verify). It does not elaborate on the meanings of 'inconclusive' or 'refuted' edge cases, but the essentials for correct invocation are present.

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

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

Schema description coverage is 100%, and the schema already provides detailed explanations for both 'claim' and 'tolerance_pct', including the override behavior and default. The main description adds no additional parameter semantics but does not need to since the schema fully covers them. 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 uses a specific verb ('validate') and resource ('claim') and immediately establishes the tool's scope with natural-language query examples ('fact check', 'verify the claim that...'). It clearly distinguishes this tool from general question-answering siblings by stating it returns a verdict on factual truth, making the purpose unmistakable.

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

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

Explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also gives an alternative by noting it 'Replaces 4–6 sequential calls,' and explains how different claim types route to different pipelines, providing clear context for selecting 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.