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?

Annotations declare readOnly/idempotent/openWorld/non-destructive, and the description adds non-obvious behavior: routing among 5,798 tools, filling arguments automatically, and returning structured answers with stable pipeworx:// citation URIs. No contradiction with annotations.

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

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

Front-loaded with the primary instruction, and each block—domain list, examples, exclusions—earns its place. Slightly long because of the repeated example categories, but not bloated.

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

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

There is no output schema, and the description compensates by specifying the return shape (structured answer with stable citation URIs), giving representative examples, and naming sibling alternatives. For a router tool this covers the essential calling context.

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 all six parameters are aliases for the same required 'question' field, documented in the schema. The description reinforces natural-language question input with examples but does not need to add parameter-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?

Description starts with a directive 'PREFER OVER WEB SEARCH' and enumerates exact domains (SEC filings, FDA, FRED/BLS, etc.) and question phrasings. It also positions the tool against siblings by naming when ask_pipeworx_grounded and deep_research should be used instead.

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 says 'START HERE for most questions' and 'Use whenever the user asks...', giving concrete triggers. It explicitly excludes multi-step research to ask_pipeworx_grounded and broad fan-out research to deep_research, plus notes news is already handled through ask_pipeworx.

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, the description discloses that this is an experimental edge, that candidate routing improvements may be live under test, that no candidate is currently active, and that it is a full working router with no fallback. This gives agents accurate expectations about variability, reliability, and current equivalence to the stable tool.

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 compact paragraph that front-loads identity and current equivalence, then gives usage guidance and fallback behavior. It is slightly long but each sentence contributes meaningful operational 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 an open-world router with no output schema, the description covers purpose, current state, usage, relationship to the stable counterpart, and experimental risk. No critical operational detail appears missing for an agent deciding whether and how to call this tool.

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

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

Schema description coverage is 100%, with all parameters and aliases already documented. The description adds only that it accepts the same arguments as ask_pipeworx, which is useful context but does not materially expand parameter understanding beyond the schema.

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

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

The description clearly identifies this as the beta variant of ask_pipeworx, a universal router with the same 5,798 tools, arguments, and response shape. It also states the current status — no candidate routing improvement active — so an agent understands exactly what this tool is and how it relates to the stable version.

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

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

The description explicitly tells the agent to use it exactly like ask_pipeworx when the newest routing is desired, and explains that results feed into comparing candidate improvements against the stable router. It does not explicitly enumerate when NOT to use it or mention ask_pipeworx_grounded as an alternative, but the usage context is clear.

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

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

The description adds substantial behavioral detail beyond the annotations: refusal reasons, evidence/verbatim quote behavior, explicit success and refusal return shapes, and the fact that it makes an extra LLM call. These details are not visible in annotations or the schema, and nothing contradicts the readOnly/openWorld/idempotent hints.

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

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

Every sentence earns its place: the first sentence captures the core purpose, the middle covers mechanism and return/refusal behavior, and the final sentence gives actionable routing advice. It is dense but not bloated, and the most important differentiator is front-loaded.

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

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

With no output schema, the description compensates fully by describing both success and refusal return payloads, refusal reason enums, and behavioral guarantees. The required parameter is obvious from both the title and the schema, and the cost/usage tradeoff is stated, making this 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 has 100% description coverage, including aliases for the required question parameter, so the description does not need to re-explain parameters. The description adds no new parameter semantics beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description clearly identifies this as a grounded, hallucination-resistant answer mode for ask_pipeworx and explains its distinguishing behavior: it extracts answers only from tool results and refuses when data is insufficient. This differentiates it from sibling tools like ask_pipeworx and ask_pipeworx_beta without ambiguity.

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

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

The description gives explicit when-to-use guidance ('whenever an answer will be quoted, cited, or acted on... must not invent facts'), names concrete high-stakes domains, and explicitly says to prefer ask_pipeworx for casual lookups. It also mentions the cost tradeoff, which helps an agent choose rationally.

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 already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds rich behavioral context beyond the schema: parallel decomposition, gap[] semantics ('never invented'), hop field, contradiction[] scans, semantic excerpting not head-truncation, expected latency ranges, and the citation_uri fetchability guarantee. This goes far beyond what annotations offer.

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 carries load-bearing information—auth requirements, routing logic, gap semantics, citation guarantees, latency. The critical usage constraint (account required, use ask_pipeworx if not signed in) is front-loaded. Slightly dense prose with parentheticals makes it a bit harder to parse, but no sentence is wasted.

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

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

For a complex tool with 2 params, 100% schema coverage, and no output schema, the description explains the return packet (verbatim evidence + confidence + source + fetched_at + pipeworx:// citation + gaps[] + hop field + contradictions[]) in enough detail that an agent can set expectations without an output schema. It also covers failure modes (empty gaps for news topics), timing, auth, and tier differences. Nothing critical is missing.

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

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

Schema coverage is 100%, so the schema already thoroughly documents both parameters, including the depth enum semantics. Still, the description adds meaningful value by explaining what depth tiers mean operationally (quick=single hop, standard=gap-recovery hop + contradictions, thorough=paid iterative hop), latency implications per tier, and that question supports broad/multi-part natural language. This enhances rather than merely repeats 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 is exceptionally specific: it names the verb ('research'), the resource ('Pipeworx's 1517 STRUCTURED data sources'), and the mechanism ('decomposes..., routes to 5,798 tools in parallel, returns findings packet'). It also explicitly distinguishes itself from open-web search and names sibling ask_pipeworx as the alternative for single lookups, which prevents confusion among the crowded sibling list.

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 ('broad/multi-part questions over structured data'), when-not-to-use ('For a single lookup use ask_pipeworx'), and addresses auth/plan constraints ('ACCOUNT REQUIRED... if not signed in, use ask_pipeworx instead'). It even covers edge cases like news topics routing to ask_pipeworx. This is textbook 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?

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?

Annotations already declare read-only, idempotent, and non-destructive behavior, and the description adds substantial context beyond that: fan-out across specific government and corporate databases, soft-failure of the USPTO PatentsView API, GDELT-to-GNews fallback, empty sections meaning genuine no-data, and resolved:false for private companies. This is far more than annotations alone provide.

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

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

The description is long but densely informative and front-loaded with intent examples and the key preference rule. Nearly every sentence carries operational meaning, though some trimming of the return-structure enumeration would improve readability without losing essential guidance.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so exhaustively: sources_used/sources_failed semantics, each returned section with caveats, source-specific limitations, fallback chains, and resolution failures are all covered. The tool's complexity is matched by a complete, decision-ready description.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description still adds value by showing accepted shapes (ticker, zero-padded CIK, or company name), clarifying that 'company' and 'ticker' are interchangeable, and explaining name resolution behavior and the private-company edge case.

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

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

The description opens with concrete user-intent examples and then states the core function: a 'full cross-source profile of a US public company in ONE parallel call.' It names the verb, resource, and scope, and differentiates itself from chaining single-source lookups.

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

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

The description explicitly instructs to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' and it notes the private-company case where resolution fails. This gives clear usage context, though it does not name specific sibling tools like compare_entities or resolve_entity as 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 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?

Even with readOnly/openWorld/idempotent annotations, the description adds substantial behavioral context: fees are not modeled, matching is keyword-based and can produce non-equivalent bet shapes, compatibility codes can be non-empty even when pairs are returned, unclassified legs are never paired, and null temporal alignment means unknown rather than aligned. This rich disclosure goes far beyond the annotation set.

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

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

The description is thorough and labels major sections (TWO MODES, RESPONSE, SAFETY FIELDS), but it is very long and somewhat redundant, repeating that both modes run the identical matcher and reiterating the temporal-alignment caveat. It earns a pass because of the tool's complexity, but it is not tightly edited enough for a 4.

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 must explain return values and edge cases, and it does so exhaustively: `compatibility_warning`, `compatibility_codes[]`, `top_spreads_pp` flags, `skipped_unclassified`, `low_confidence_pairs[]`, `temporal_alignment`, `fees_note`, and `skipped_cross_type/subtype`. A caller would have nearly everything needed to interpret and act on the response correctly.

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

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

The input schema already covers 100% of the parameters with descriptions, including the topic enum values and override semantics for the two explicit parameters. The description adds context about modes and that both modes run the same matcher, but it does not meaningfully deepen parameter-level meaning beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description immediately states the tool computes a 'cross-venue spread between Kalshi and Polymarket for the same resolving question', which is a specific verb-resource pairing. It also clarifies scope by noting the two venues, the matching logic, and the two modes, so an agent can distinguish it from sibling Polymarket tools like polymarket_arbitrage or polymarket_edges without opening the schema.

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

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

The description gives clear usage context: it explains two modes (`topic` shortcuts vs explicit ticker/slug), when each applies, and warns that pre-mapped topics often return compatibility warnings and are not automatically tradeable. It does not explicitly name alternative sibling tools or say 'when not to use this tool', so it just misses the top score.

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

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

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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes far beyond these by disclosing multi-source cascading lookups, graceful degradation when GLEIF/OpenFIGI is unavailable, explicit `unresolved` reporting instead of omission, and the `figi_candidates` behavior when a name matches multiple instruments. These are high-value behavioral details an agent would not otherwise know.

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

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

The description is information-dense and front-loaded with examples and the primary use instruction, but it becomes sprawling with long parentheticals, nested caveats, and semicolon chains. Most content earns its place, but the structure is harder to parse than it should be for an agent scanning quickly.

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 must explain what the tool returns, and it does: canonical identifiers, source labels, unresolved identifiers, and `figi_candidates`. It also covers edge cases like non-US issuers, non-equity instruments, multiple matches, and enrichment failures. The tool is more than adequately specified for correct invocation.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema: accepted input forms for `value`, examples like 'AAPL' and 'CH0038863350', the ISIN-to-LEI mapping, the warning to pass the issuer name exactly as printed and never the full noun phrase, and the distinction between brand and generic drug names. This directly prevents common invocation mistakes.

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 action — resolving a user-spoken name to canonical/official identifiers — and names the exact resources ('company', 'drug') with their identifier systems (CIK, ticker, LEI, FIGI, RxCUI). It is clearly differentiated from siblings like entity_profile and compare_entities by emphasizing 'other tools require as input' and 'Use FIRST whenever you have a name but need an ID.'

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 routing guidance: 'Use FIRST whenever you have a name but need an ID.' It also defines accepted input forms and entity types. It does not explicitly name alternative tools or state when NOT to use this tool, but the guidance is strong enough for an agent to select it in the intended cases.

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

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

Annotations already declare readOnlyHint, 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.