Herb Tcm

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds meaningful behavioral context: the default model is free, Anthropic calls require a BYO key with direct cost to the user, and the response structure includes per-model score, confidence, signals, and raw_response. This complements the annotations without contradiction.

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

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

The description is front-loaded with the core purpose and result, then details the default model and optional Anthropic integration, and ends with use cases. It is efficient and avoids fluff, though it could be slightly tighter. Each sentence earns its place, so it merits 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?

For a read-only, idempotent tool with no output schema, the description adequately explains the return format (per-model structure plus combined view) and covers all parameters via the schema. It also provides usage context. No critical information is missing for an agent to call it correctly, though error handling and rate limits are not addressed.

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 all four parameters are already documented in the input schema. The description adds marginal value by reiterating the default model and the _apiKey's purpose, but it does not introduce new parameter semantics 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 states a specific verb ('Probe') and resource (LLMs), and clearly defines the outcome: scoring visibility from 0-100 per model. It goes beyond the title by specifying the default model and the option to probe Anthropic, and lists concrete use cases, making the purpose unmistakable even among many sibling tools.

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

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

The description provides clear contexts for use ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), which implicitly tells when to invoke it. However, it does not explicitly name alternatives or state when not to use it, so it falls short of the highest level of guidance.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior, so the bar is lower. The description adds valuable behavioral context: it fills arguments automatically, returns stable pipeworx:// citation URIs, works on every tier, is fast, and implicitly warns that it is not hallucination-resistant by pointing users to ask_pipeworx_grounded for that guarantee.

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 appropriately so for a default routing tool with many siblings. It front-loads the most important instruction, then provides domains, trigger phrases, examples, and sibling differentiation. There is some overlap between the trigger phrases and examples, but it remains structured and purposeful rather than 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?

For a tool with a single free-text parameter, no output schema, and a broad mandate, the description is unusually complete. It covers scope, mechanics, alternatives, examples, tier availability, and even addresses the news use case. The only minor omissions are failure behavior and exact output formatting, but the structured-answer-with-citations promise 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?

The schema covers 100% of parameters, documenting all six aliases (question, q, text, input, query, prompt). The description adds usage examples and trigger phrases, but it does not add parameter-specific 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 opens with a clear directive ('PREFER OVER WEB SEARCH') and states the tool's function: route a factual question to the right one of 6,232 tools and return a structured answer with citations. It also differentiates itself from siblings by naming ask_pipeworx_grounded and deep_research as step-ups, while positioning itself as the default entry point.

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 extremely explicit when-to-use guidance, listing specific data domains, trigger phrases, and example questions. It also explains when to step up to alternatives (grounded for verbatim evidence, deep_research for broad multi-part questions) and notes that ask_pipeworx already handles live news so no separate news tool is needed.

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

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

The description goes well beyond the read-only/idempotent annotations by disclosing that candidates may be enabled live, that no candidate is currently active, that it currently behaves exactly like ask_pipeworx, and that it does not fall back—this is a fully working router. 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 well ordered: identity, current candidate status, usage instruction, comparison purpose, and no-fallback clarification each earn their place. The most decision-relevant facts, beta, matches stable now, use like ask_pipeworx, are front-loaded.

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

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

Given no output schema, the description could be more explicit about response shape, but it defers to ask_pipeworx's response shape, which is acceptable if that sibling definition is visible. The main completeness gap is the unaddressed relationship to ask_pipeworx_grounded.

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 every parameter is documented as an alias for 'question,' so the schema carries the semantic load. The description merely says 'same arguments' and adds no parameter formatting or composition guidance beyond what the schema provides.

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

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

Clearly identifies itself as a beta universal router identical to ask_pipeworx, same 6,232 tools, same arguments, and same response shape, with an experimental routing role. However, it does not explicitly distinguish itself from the similarly named sibling ask_pipeworx_grounded, relying on the reader to infer the difference.

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?

Gives an explicit condition: 'Use it exactly like ask_pipeworx when you want the newest routing,' and explains that results are compared against the stable router to decide merges. It does not state when to avoid it or how it compares to ask_pipeworx_grounded, so the exclusion guidance is partial.

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 substantial behavior beyond the annotations: it returns a structured object with evidence (verbatim quote), confidence, source, and fetched_at; it may refuse to answer and enumerates the five refusal reasons; and it explicitly states the guarantee that the answer is extracted only from the tool result. The annotations (readOnly, openWorld, idempotent, non-destructive) are consistent and the description adds important operational context like the extra LLM call cost.

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

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

The description is front-loaded with the core purpose ('Hallucination-resistant answer mode') and then delivers all essential details in a compact, well-organized flow: routing behavior, return structure, refusal cases, use cases, and cost trade-off. Every sentence earns its place, and there is no filler or redundancy.

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

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

There is no output schema, so the description fully compensates by spelling out the exact success response shape and the refusal response with all possible refusal_reason values. It also covers when to use the tool and its cost implication. For a read-only question-answering tool with this complexity, nothing an agent needs to call it correctly is missing.

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

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

The schema already provides 100% description coverage, with the 'question' parameter and all aliases fully documented. The description does not add new parameter semantics beyond implying the input is a natural-language question, which the schema already states. Per the baseline rule, a 3 is appropriate when the schema carries the full weight.

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, evocative purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes itself from the main sibling by stating it 'extracts the answer using ONLY what the tool result contains,' which contrasts with the regular ask_pipeworx. The differentiation extends to cost and use case, making it easy for an agent to know exactly what this tool does and how it differs.

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

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

Explicit usage conditions are given: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also names the alternative and the trade-off: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This leaves no ambiguity about when to choose this tool over its sibling.

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 cover only the safety profile (readOnly/openWorld/idempotent/non-destructive), and the description adds far beyond that: BLOCKING short-circuit statuses (low_confidence_match, market_closed_or_inactive, market_expired_or_resolved), the resolver contract with match confidence scores, GDELT 429 fallback fields, illiquid_wide_spread flagging, and cancellation-rule settlement parsing. These are exactly the operational traits an agent needs to avoid misusing results (e.g. sizing on phantom matches).

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?

Purpose is front-loaded, but the body is an unusually dense wall of ALL-CAPS headers and enumerated classifier/fan-out/status lists. Much of this is useful given the absent output schema, yet the density and length exceed what most agents will parse, so structure is adequate but not economical.

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 return-shape burden and does so: result.market fields, result.analysis fields (model_probability/edge_pp/kelly_fraction_half), result.evidence keying, resolver contract fields, parent_event partition fields, and news fallback metadata are all documented. An agent can interpret responses without guessing.

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 genuine meaning: it explains WHY to prefer an undated slug (dated slugs stop resolving once settled because Polymarket de-indexes resolved markets) and ties fuzzy matches to the suggestions[]/market_match_alternatives[] re-query hints. The depth and include_raw semantics largely restate the schema, so it is not a full 5.

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') and enumerates the full pipeline (resolve → classify → fan out → evidence packet + model comparison). Sibling Polymarket tools (edges, arbitrage, fill_risk, kalshi_spread) are implicitly distinguished by the 'should I bet on X / what does the data say / is there edge' trigger framing, which reads as research rather than scanning or spread-monitoring.

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?

Trigger phrases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') give clear usage context, and the safety section explains when the tool effectively won't produce analyzable output. However, it never names an alternative sibling or states when NOT to use this tool (e.g. bulk edge-scanning belongs to polymarket_edges/arbitrage), so routing vs. alternatives is left to inference.

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

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

Annotations only declare safe read-only behavior; the description adds substantial behavioral detail beyond that: it NEVER substitutes periods, NEVER returns 0 for missing data, NEVER lets YTD answer quarterly, and NEVER converts currency. It also discloses data provenance, status semantics, and response contents including concept, accession, restatement trail, and contract version.

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 fairly long, but it is front-loaded with the core purpose and examples before moving to behavioral guarantees and status semantics. Nearly every sentence adds distinctive information, though some stylistic repetition and capitalization could be trimmed without losing meaning.

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

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

Despite having no output schema, the description compensates by detailing exactly what every answer carries, enumerating all non-answer statuses, and describing source behavior and restrictions. Combined with the fully documented 9-parameter schema, an agent has enough context to select and invoke the tool correctly.

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

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

The input schema has 100% parameter description coverage, so the schema already explains period, company, attribute, and other parameters. The description reinforces key ideas like filer-defined fiscal years and the ambiguity handling for company names, but it mostly restates or complements rather than adding substantially new parameter-level 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?

States a specific resource and scope: 'financial facts for a US public company for an EXPLICITLY NAMED reporting period,' with concrete examples. It also differentiates itself from entity_profile / get_company_financials by emphasizing deterministic period-matched facts rather than latest figures.

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 'PREFER OVER entity_profile / get_company_financials whenever the period matters' and explains why those alternatives may return the wrong period. It also enumerates non-answer statuses such as unavailable, unsupported, ambiguous, and conflicting, which clarify when this tool is and isn't appropriate.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds substantial behavioral context beyond those annotations, including data sources (SEC EDGAR/XBRL, FAERS), fiscal-year handling, sorting by primary metric, and citation URI returns. 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?

The description is information-dense and front-loaded with trigger phrases and the main instruction. While it is relatively long, the additional details about data provenance, sorting behavior, and fiscal-year handling earn their place in helping an agent invoke the tool correctly.

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 input constraints (via schema), data sources, return content, sorting, and citation URIs, which is especially valuable since no output schema exists. Minor gaps remain around units, currency, or clear error cases, but overall the agent has enough context to use the tool properly.

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 meaning beyond the schema by clarifying what each 'type' maps to (company financials vs. drug adverse-event/trial data) and by explaining values as tickers/CIKs or drug names. It also enriches the 'type' enum with concrete business details.

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

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

The description clearly identifies a specific operation (side-by-side comparison) and resource (2–5 companies or drugs in one parallel call). It also distinguishes itself from sequential single-pack lookups, making its purpose unambiguous relative to sibling tools.

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

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

The description explicitly says to prefer this tool over sequential single-pack lookups when comparing entities aid provides natural-language trigger phrases. It lacks explicit mention of exact alternative sibling tools or clear 'when not to use' scenarios, but the intended usage context is very 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 goes far beyond the annotations. It discloses the account requirement, the paid tier for 'thorough' depth, the parallel decomposition behavior, the findings packet structure (verbatim evidence + confidence + source + fetched_at + citation), the gaps[] behavior (never invented), the hop field and citation_uri resolvability, the contradictions[] scan, the semantic excerpting behavior, and the expected latency. The annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are consistent with the description, and the description adds substantial behavioral context that the annotations don't cover.

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

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

The description is long but every sentence earns its place: account requirements, routing guidance, behavioral details, latency expectations, and citation semantics are all packed in. It's front-loaded with the most critical operational constraint (account required) and the alternative tool. It could be slightly more concise, but the density of useful information justifies the length.

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 2 parameters, no output schema, and rich annotations, the description is remarkably complete. It covers prerequisites (account), alternatives (ask_pipeworx), behavior (decomposition, parallel routing, gap recovery, contradictions), output format (findings packet with evidence/confidence/source/fetched_at/citation), edge cases (breaking news returns empty gaps), and performance expectations (15-90s). An agent has everything it needs to decide whether and how to invoke 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 coverage is 100%, so the schema already documents both parameters. The description adds value by explaining the depth parameter's behavioral implications (gap recovery, contradiction scan, paid tier) and by clarifying that the question parameter accepts broad/multi-part natural language. The description doesn't add syntax details, but the schema already covers the enum values and the description enriches their 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's purpose: grounded multi-source research across Pipeworx's structured data sources in one call. It explicitly distinguishes itself from open-web search and from ask_pipeworx, and provides concrete examples of the kinds of questions it's for. The verb 'research' plus the resource ('1623 STRUCTURED data sources') and the decomposition/parallel-routing behavior make the purpose unmistakable.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and explicitly says to use ask_pipeworx for single lookups and for breaking/current-news topics. It also names the alternative tool and the condition that selects it. This is exactly the kind of routing guidance an agent needs.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior; the description adds substantial value by disclosing the exact return shape: top-N relevant tools with names, descriptions, full input schemas and curated examples, and that results are ready to call without a second schema lookup. This is especially useful because no output schema is provided.

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

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

The description is front-loaded with the core purpose, followed by use cases, return value, and a clear first-step instruction. Each sentence earns its place, and the domain list is dense but directly relevant.

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 discovery tool with straightforward parameters, high schema coverage, and no output schema, the description fully compensates: it explains what the tool does, when to use it, and exactly what the response contains. Nothing materially needed by an agent 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%, and the schema already documents query, all aliases, and limit defaults/max. The description only restates that the input is a natural-language description of a data/task, adding no parameter-level meaning beyond the schema.

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

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

The first sentence names a specific action and resource: 'Find tools by describing the data or task.' It also lists concrete domains and frames the tool as a discovery/meta tool, which distinguishes it from the many operational sibling tools and clarifies it is not itself a domain-specific search.

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 when to use it ('Use when you need to browse, search, look up, or discover what tools exist') and instructs to call it FIRST when many tools are available. It does not name specific alternative tools or give explicit exclusions, though 'not just one answer' hints at when a direct tool is more appropriate.

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

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

Annotations already promise a safe read-only, idempotent operation, and the description adds substantial behavioral detail: soft-failing USPTO API until reactivation, sources_used/sources_failed/sources_skipped tri-state semantics, empty sections meaning real no-data rather than bugs, and the SIC-based skip rule for the Purple Book. It also explains name resolution via EDGAR and private-company handling. This far exceeds what annotations convey.

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

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

The description is dense but not bloated: every source, return field, and state has a purpose. It front-loads trigger phrases and the core value proposition before diving into details. The single-paragraph format is a bit heavy, but given the tool's complexity it is structured and readable.

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 enumerating the return sections, source states, skip reasons, and the resolved/resolved_from/resolved_to details. It also covers input resolution, failure semantics, and the meaning of empty arrays. Nothing critical is missing for an agent to call this tool correctly.

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

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

Schema coverage is 100% for both parameters, and the description reinforces and expands on them: type takes company or ticker interchangeably and value can be a ticker, zero-padded CIK, or company name. It provides a concrete example and describes the resolution outcome for private companies, making parameter selection unambiguous. This adds real value beyond the schema.

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

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

The description opens with concrete user phrasings and states a clear mission: build a full cross-source profile of a US public company in one parallel call. It distinguishes itself from single-domain lookups by explicitly naming the fan-out across SEC, XBRL, patents, contracts, FDA, H-1B, news, and GLEIF. The resource and scope are 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?

It explicitly says to ALWAYS PREFER this tool over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view. It also covers edge cases like private companies returning resolved:false and person/place not yet supported, which helps an agent decide when it is not applicable. It could name more sibling tools like company_facts or compare_entities, but the primary routing rule 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 explicit 'Delete' verb aligns with the annotations destructiveHint=true and readOnlyHint=false, and key-based deletion is consistent with idempotentHint=true. No contradiction. The description adds context beyond the flags by scoping the target to 'previously stored memory by key' and by noting the sensitive-data use case, though it does not describe edge-case behavior like deleting a missing key.

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

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

Three short sentences with the core action front-loaded, followed by usage triggers and sibling pairing. Every sentence earns its place; there is no filler or redundant restatement of 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?

For a one-parameter delete action, the description covers purpose, usage conditions, sibling context, and destructive nature; annotations cover idempotency and mutation, and the schema covers the parameter with an example. Nothing material an agent needs to invoke the tool correctly is missing.

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

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

Schema coverage is 100% and the schema already documents key as 'Memory key to delete' with an example. The description merely restates the mechanism as 'by key,' adding no format, lifecycle, or edge-case semantics beyond what the schema provides. 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 a specific verb ('Delete') with a specific resource ('previously stored memory') and the mechanism ('by key'). The description also names the paired sibling tools remember and recall, making the tool's role in the memory family 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?

Gives three explicit trigger conditions: stale context, task complete, and clearing sensitive data previously saved by the agent. Names the related tools remember and recall as its pair, though it stops short of an explicit when-not-to-use statement.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context by explaining that it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. It does not cover failure modes or rate limits, but the annotation coverage lowers the bar for this dimension.

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: purpose, process, and use cases. It is front-loaded with the core action, contains no fluff, and 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?

For a two-parameter tool with no output schema, the description is sufficient: it specifies the output format ('single text blob ready to drop at site-root/llms.txt'), the process, and the use cases. Minor gaps like error handling are not critical 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%, so the schema fully documents both url and max_links. The description does not add parameter-specific semantics beyond what the schema provides, which is acceptable; the baseline of 3 applies.

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

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

The description states a specific verb ('Generate') and resource ('llms.txt file for any URL'), and explains the process (fetch, extract, emit). It does not explicitly contrast with siblings like ai_visibility_check, but the purpose is unambiguous and clearly distinct from the other tools.

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

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

The description provides concrete use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context for when to use it. It does not mention when to prefer a sibling or any exclusions, 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds useful context by stating the full scope and exact record counts per category, which helps an agent estimate the size of the result space and treat this as a broad enumeration operation.

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

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

Two sentences with no wasted words: the first states what the tool does and the scope, and the second routes to the appropriate alternative. The most important information is front-loaded.

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

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

For a simple paginated browse tool, the description is complete: it specifies the data source, the four browsable categories, the approximate size of each list, pagination wording, and when not to use it. No output schema is present, but the description gives enough context for correct invocation and expectation-setting.

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 does not add parameter-level detail beyond the schema; it restates the categories and implies pagination, but the schema already documents page, category, and page_size with defaults and constraints.

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

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

The description uses a specific verb ('Page through') and resource ('HERB 2.0's full herb, ingredient, target or disease list') and explicitly enumerates the four categories. It also names the sibling tool herb_search, which makes the differentiation clear.

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

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

It explicitly instructs to use herb_search instead when a name is already known, providing a clear when-not condition and an alternative. This is the exact kind of routing guidance agents need.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description adds rich behavioral context beyond that: computational_prediction is defined as hypothesis-level, traditional_use is distinguished from clinical trial evidence, and pagination semantics (total vs truncated) are disclosed. It also warns against misrepresenting predicted edges as proof.

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 specific, non-redundant value. It front-loads the core purpose and then covers evidence tiers and pagination; the only minor cost is length, but the density is justified for a complex data tool.

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, so the description carries the full burden of explaining return structure, and it does so: relationship rows include evidence_tier, paged tables have {total, offset, limit, returned, truncated, rows}, and `truncated:true` signals more rows. The evidence-tier semantics and section-narrowing guidance make 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?

Although schema coverage is 100%, the description adds meaning by explaining the default 25-row return, the significance of `total` as the true upstream row count, and how `sections` can narrow the payload. This exceeds the schema's parameter descriptions and helps an agent choose values intelligently.

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

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

The description names a specific resource ('Full record for one HERB id') and enumerates the four category variants (herb, ingredient, target, disease) with their component contents enough to distinguish the tool from herb_search or herb_browse. It also states the evidence-tier labels clearly, making the operation's scope unambiguous.

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

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

The description gives concrete operational guidance: use `sections` to narrow, use `offset` to page, and expect `truncated:true` when more rows exist. It does not explicitly compare against sibling tools like herb_browse or herb_search, but it clearly explains when this detail endpoint is appropriate and how to avoid pulling huge result sets.

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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds valuable context: that results are computational predictions, not validated clinical findings, which is critical for an agent to appropriately convey uncertainty. This goes beyond annotations by providing epistemic status.

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 paragraph that front-loads what the tool returns and immediately disclosures the evidence tier. Every sentence adds value: first sentence lists outputs, second sentence warns about the computational nature. 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?

Given the tool's simplicity (single parameter, no output schema, low complexity), the description covers all necessary aspects: what is returned, the nature of the data, and the safety profile via annotations. No critical information is missing for an agent to use it correctly.

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

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

The schema already fully documents the single parameter (experiment_id) with an example and format, so schema coverage is 100%. The description does not add further parameter-specific details, but with full coverage a baseline of 3 is appropriate. No additional nuances are needed.

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

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

The description states a specific purpose: retrieving differential-expression results for one HERB transcriptomic experiment, listing the exact outputs (top up/down-regulated genes, GO terms, KEGG pathways, connectivity-map counts). This clearly distinguishes it from sibling tools like 'herb_experiments' (likely listing experiments) and 'herb_detail' (general entity 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 implies it is used when an agent needs results for a single experiment, given an experiment_id. It does not explicitly state when not to use it or name alternatives, but the context of sibling tool names and the schema (requiring an experiment_id) makes usage clear. No explicit exclusions are provided, but it's adequate for most call scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description's job is lighter. It adds useful context beyond the annotations: the data is GEO-deposited, represents treatment-vs-control experiments, and serves as evidence for downstream predictions. No behavioral contradiction is present.

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

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

Two sentences with no filler. The core verb, resource, and scope are front-loaded, and the second sentence efficiently lists the available filters. Every clause earns its place.

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

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

For a read-only list tool with annotations covering safety and schema covering pagination defaults, the description is nearly complete: it states what is listed, the experimental design, data source, and connection to herb_experiment_detail. The main gap is the platform/experiment_type naming mismatch, which slightly undermines an otherwise sufficient 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 only 40%, so the description should compensate for the three undocumented filter parameters. It does mention drug_type and species accurately, but it calls experiment_type 'platform' — a term that does not match the actual schema property and could cause an agent to pass a nonexistent parameter. It also adds no meaning to the enum values, making the compensation incomplete and partly misleading.

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 uses a specific verb ('List') and a precise resource ('HERB's transcriptomic experiments'), then clarifies the experimental design ('herb/ingredient treatment vs. control, GEO-deposited'). It also differentiates itself from the sibling herb_experiment_detail by positioning itself as the raw-evidence layer behind differential-expression predictions.

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 this tool is relevant: it lists raw evidence behind predictions that appear in herb_experiment_detail. It stops short of explicitly naming alternatives or saying when not to use it, but the relationship to the detail tool is strong enough to guide selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds context about what the tool returns (bibliographic record and tagged targets/diseases) and how evidence tier is assigned. It does not mention pagination, limits, or potential variations in output, but for a single-record lookup the provided information is adequate.

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 with no fluff. The core functionality is front-loaded, and the usage hint is appended succinctly. Every word adds value, making it an efficient and well-structured definition.

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 read tool, the description covers what is returned, how the evidence tier is tagged, and where to obtain the required id. With no output schema and annotations covering safety, this is sufficient. Minor gaps like error handling or edge cases are not critical for this type of tool.

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

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

Schema coverage is 100% with paper_id described as a HERB reference id. The description reinforces the format with an example (HBREF000003) and clarifies the source of the id, adding value beyond the schema. Since coverage is high, the baseline is 3, and the description provides extra semantic guidance, earning a 4.

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

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

The description clearly states the tool returns a reference's bibliographic record plus specific targets/diseases with evidence tier. It specifies the exact fields (journal, PubMed id, experiment type, phenotype) and how evidence tier is derived. While it doesn't explicitly name sibling tools, the mention of 'herb_detail' and 'herb_papers' as sources for the paper id provides some differentiation context.

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

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

The description gives guidance on where to obtain the paper_id (from drug_paper_target/drug_paper_disease rows or herb_papers), which is useful for invocation. However, it does not explicitly state when to use this tool versus alternatives like herb_experiment_detail or herb_papers, nor does it mention when not to use it. The usage context is implied but not fully articulated.

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, destructiveHint=false, so the tool is safe and idempotent. The description adds context about the underlying data source (PubMed) and the full index size (~2,000 references), plus the evidence tier classification. It doesn't contradict annotations and adds meaningful context about what the tool does beyond safety.

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

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

Two sentences, front-loaded with the core purpose and key detail (evidence tiers), then the filtering guidance. No wasted words; the description includes all essential info without redundancy. It earns its place by covering purpose, tags, filters, and usage in a compact form.

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

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

Given the tool's simplicity and rich annotations (read-only, open-world), the description covers everything needed: what it lists, how to filter, how to page, and what the evidence tiers mean. The output schema is absent, so the description doesn't need to describe return format; it suffices for correct invocation. No open questions remain.

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 well-documented in the schema. However, the description adds value by explaining the experiment_type filter with examples and clarifying that 'Clinical Experiment' maps to human_clinical tier. It also explains the limit parameter's behavior (max 100, fetched upstream) in the schema already, but the description ties parameters to the overall purpose. The description doesn't repeat schema details but adds conceptual context.

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

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

The description states a specific verb ('List') and resource ('PubMed-cited papers in HERB's reference index') and explains the purpose (literature backing for herb/ingredient associations). It clearly distinguishes from siblings like herb_search (which searches) and herb_detail (which likely shows a single herb), and mentions the paper detail tool as a follow-up. The evidence tier tagging adds specificity beyond a generic 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?

Explicitly states when to use this tool: to list referenced papers, with optional filters by drug type or experiment type, and when to leave blanks (to page through all references). It also hints at when not to use it (if you need detail on a specific paper, you'd use herb_paper_detail, implied by the sibling name). The description provides clear conditional usage 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 declare readOnly, openWorld, idempotent, and non-destructive behavior, so the bar is lower. The description adds meaningful behavioral context: alias resolution across Chinese, pinyin, English, Latin, gene alias, and ID; the fact that multiple name forms resolve to the same record; and that the tool deliberately carries no evidence tiers.

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

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

Three sentences with no filler; the first sentence front-loads the core capability and accepted search terms, the second explains the return contract, and the third disambiguates from evidence/relationship tools. 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?

With no output schema, the description appropriately states that the tool returns matching IDs for herb_detail and preemptively clarifies it has no evidence tiers. Schema covers both parameters fully and annotations cover safety. It does not describe output formatting or empty-result behavior, but that is not critical for a simple lookup 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%, so the baseline is 3; the description adds value beyond the schema by giving concrete alias examples ('板蓝根', 'banlangen', 'Dyers Woad', 'BAN LAN GEN') and explaining that results are matching IDs intended for herb_detail. This enriches the keyword parameter meaning without duplicating the schema.

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

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

The description names a specific action and resource: 'Search HERB 2.0' across herbs, ingredients, gene targets, or diseases. It distinguishes itself from siblings by clarifying that it returns IDs intended for herb_detail and explicitly states it is a name lookup, not a relationship/evidence tool.

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

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

The description provides practical routing guidance by saying the tool returns matching IDs to pass to herb_detail, and excludes relationship/evidence usage. It does not explicitly enumerate when not to use it versus other herb siblings like herb_browse, but the downstream reference gives a clear usage context.

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

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

The description goes far beyond the annotations by disclosing non-obvious behavioral traits: markets settle on Weather Company, not NWS; station is derived from settlement clause; forecast_prob uses an assumed normal distribution; edge_pp is gross; and it exposes a concrete measured result showing the market beat the forecast. These are exactly the kind of caveats an agent needs to interpret results correctly, and they are not visible in the read-only/open-world 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 tightly packed with critical trading caveats. It is front-loaded with purpose and modes, then structured warnings (1-4), then a measured result, followed by edge-case handling. While not concise, the density is justified given the financial stakes and the need to prevent misuse; it could be slightly more scannable with headers, but overall each sentence carries weight.

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 specify return values, and it does: LIVE mode returns the strike ladder with market_prob, forecast_prob, edge_pp, and the settlement clause; BACKTEST returns brier_market vs brier_forecast, settlement-vs-forecast basis, and a plain-English verdict. It also covers international and precipitation fallbacks, and the warning section covers all major edge cases. Nothing an agent needs to call the tool correctly is missing.

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

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

Schema coverage is 100%, but the description adds substantial meaning to each parameter: 'city' includes a default and fallback behavior (unmapped cities return known_cities[]), 'date' explains open/close timing, 'market_type' clarifies precipitation returns no forecast, 'backtest_days' explains the scoring methodology and max, and 'series_ticker' overrides city. This is a textbook example of enriching schema with operational context.

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

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

The description clearly states the tool's function: 'Prices Kalshi daily high-temperature markets against the NWS forecast...' and explicitly defines two modes (LIVE and BACKTEST) with distinct outputs. It differentiates itself from sibling tools by focusing on a niche weather-edge analysis, and the many specific details (station codes, edge_pp, brier scores) leave no doubt about 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 explicit when-to-use guidance: 'LIVE (default)' vs 'BACKTEST (`backtest_days: N`)', and tells the user to run backtest before believing any edge. It also covers exclusions: international series return forecast_unavailable, precipitation is not priced, and it warns about using city-centre forecasts when stations are derived from settlement clauses. This is model-guidance beyond what any sibling alternative offers.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful behavioral detail by scoping to the caller's active subscriptions and enumerating the returned fields, which goes beyond what annotations 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?

Two sentences carry all the essential information: what the tool lists, what it returns, and when to use it. The primary action is front-loaded and there is no redundant wording.

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-only list tool with one optional documented parameter and no output schema, the description is complete: it names the resource scope, the returned fields, and the use cases. 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 description coverage is 100%, so the single optional include_inactive parameter is already fully documented. The description does not add further parameter context, which matches the baseline of 3 for 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 names a specific verb and resource: 'List the caller's active subscriptions.' It also lists the exact return fields, making the operation concrete and clearly distinct from sibling tools like 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 when to use this tool: 'review what you're monitoring before adding more' and 'find an id to cancel.' It gives clear context, though it does not explicitly name sibling alternatives or state when not to use it.

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

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

Goes far beyond the annotations: discloses the claim_token return-and-lookup flow, rate limit (5/day/identifier), cost (free, no quota), and operational facts (team reads digests daily, signal affects roadmap). Also instructs on content policy (describe in terms of Pipeworx tools, don't paste user prompts). 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 earns its place: purpose is front-loaded, the critical exclusion comes early, then workflow, then operational constraints. The length is justified by the tool's nuance (claim tokens, rate limits, server-scoping) and there is zero 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?

Despite no output schema, the description fully covers what an agent needs: when to call, what to include, what to expect (claim_token), how to follow up later, and operational limits. No important behavioral aspect is left unexplained.

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 parameters at 100%, giving baseline 3. The description adds real value beyond schema by explaining the claim_token round-trip workflow and the message content rule (mention specific tool/pack, avoid pasting user prompts). These clarify how to use the parameters correctly, lifting the score above baseline.

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 opens with a clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It names the three content categories (bug, feature/data_gap, praise) and explicitly excludes tools from other MCP servers, so an agent can immediately distinguish this from any sibling or external tool.

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

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

Gives explicit when-to-use conditions (wrong/stale data, missing catalog entry, positive experience) and an explicit when-not-to-use with an alternative action: file with the other server instead. Also provides a disambiguation heuristic ('Pipeworx tool names are the ones this connection lists'). This is exemplary routing 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that the data is self-aggregating, derived from CF analytics-engine, contains no PII, and only exposes (pack, tool, count). It also states caching behavior (5min-1h depending on window), which is useful operational context not present in the annotations.

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

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

The description is front-loaded with the core result set, then uses a compact numbered list for use cases. Every remaining sentence adds substantive value — data source, privacy, and caching — with no filler or repetition beyond the minor window mention.

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 read-only tool, the description fully covers what the agent needs: what it returns, what windows are available, how the data is derived, and that it is privacy-safe. The absence of an output schema is adequately compensated by naming the return components (top tools, top packs, total call volume).

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 for the single optional window parameter is 100%, including the enum values and an explanatory description that already notes the default and the hot-vs-steady-state tradeoff. The description reiterates the window options but does not add 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 opens with a clear purpose — what other AI agents are calling on Pipeworx right now — and specifies the exact deliverables: top tools, top packs, and total call volume over a window. This is a specific resource plus a concrete return set, making it easy to distinguish from sibling tools like discover_tools or recent_alerts.

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 three explicit use cases: discovering hot data sources, confirming a canonical tool, and aligning with aggregate agent behavior. It does not explicitly say when not to use it or name an alternative, but the 'Useful for' list gives clear contextual guidance for choosing this tool.

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

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

Annotations already mark readOnly/idempotent/non-destructive, and the description goes far beyond them: fee calculation assumptions, category-specific taker fee rates, gas modeling, fee_basis provenance, fallback behavior, fill_check repricing against live depth, and the warning that net_positive:false is a correction rather than a regression. This is unusually transparent about edge cases and limitations.

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

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

The description is long but densely packed and sectioned with clear labels (SEMANTIC ANCHOR, PARTITION FILTER, FEES, FILL CHECK) that make the content scannable. Every sentence contributes decision-relevant information, and the most important usage guidance is front-loaded before deeper fee and fill details.

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 analytic tool with no output schema, this description is remarkably complete: it covers all invocation modes, return fields (opportunities[], partition_check, fee fields), fee modeling, filtering behavior, fill-check semantics, and constraints. An agent has enough information to call the tool correctly and interpret its results without external lookups.

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 substantial meaning beyond the schema: event accepts Polymarket slugs or full URLs, topic expects a seed question, and the no-arg case is documented even though it is not a schema parameter. It also explains what each mode does with its input and what signal it produces.

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.' It further distinguishes three invocation modes (no-arg trending_scan, event, topic) and names polymarket_fill_risk as the custom-sizing alternative, so an agent can unambiguously tell this tool apart from its siblings.

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

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

Usage conditions are explicit: no args for trending scan, event 'recommended for a specific market', topic for cross-event scanning. It also explains why cross-event mode catches patterns single-event misses and redirects to polymarket_fill_risk for custom sizing, leaving no ambiguity about when to choose each path.

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. The description adds a wealth of behavioral context beyond that: it explains caching at the KV level (1h, keyed on all knobs), the response segmentation into by_segment with diagnostics, the fee handling (net of slippage and taker fee, with fees_pp_applied itemized), and the 'rare-by-design' concentration longshot gate. It even explains the logic behind excluding fed bets. This is far more than annotations 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 a single, extremely dense paragraph with heavy use of all-caps, abbreviations, and parentheticals (e.g., FIVE MODEL FAMILIES, edge_pp_net, fees.ts). While every sentence carries information, the structure is not appropriately sized for a tool description; it buries key facts like caching and diagnostics in a wall of text. It could be formatted with headings and bullet points for easier scanning. Although the content is valuable, it violates conciseness by requiring significant effort to parse.

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 (9 parameters, no output schema, multiple model families) and that annotations only cover safety, the description is remarkably complete. It explains the three response segments, diagnostics, fed_candidates, the net-of-fee edge calculation, the role of each knob, and the caching behavior. An agent can understand what the tool returns and how to invoke it correctly without needing additional 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?

Though schema_description_coverage is 100%, the description adds significant semantic depth. For example, it explains that min_partition_leg_kelly applies to per-leg Kelly within top_legs and that partition arbs return kelly_fraction_half=0 at parent level by design—details not in the schema. It also clarified the interaction between slippage_pp and the Polymarket taker fee, and the purpose of tradeable-edge knobs. This goes well beyond the schema's own descriptions.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on discovery from Pipeworx data vs. market pricing. It also states its intended use case ('what should I bet on today'), making it unambiguous.

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

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

The description provides clear context for when to use the tool—for betting opportunity discovery—and even explains why Fed bets are excluded from ranking due to unreliable data. However, it does not explicitly name alternatives or say 'use this instead of X when...', so it lacks explicit exclusions. The 'Built for' phrasing implies usage but does not cover when not to use it.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: snapshot gap semantics, TTL limits, fee-inclusive decay computation, the signed nature of edge_pp_net, expired[] lifecycle meaning, and the fact that decay uses daily closes rather than intraday data. 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 long but densely organized into Args, RESPONSE, and LIMITS sections, with the core purpose front-loaded. Some rhetorical flourishes ('the median lifespan is your competition clock') add color but not operational necessity. It earns a high score for structure, though it sacrifices some 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?

With no output schema, the description fully carries the burden of explaining return values and edge cases. It explains tracked[], expired[], snapshot_dates[], data gaps, history depth limits, and fee/slippage treatment. An agent has everything needed to call this correctly and interpret the response.

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

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

Schema description coverage is 100%, so the schema already documents both days and window fully. The description restates defaults and adds a 'max 30' note for days and the snapshot-family concept for window, but it does not introduce meaning beyond the schema's parameter descriptions. Baseline 3 is appropriate.

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

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

The description states a specific purpose: edge persistence and decay telemetry from daily polymarket_edges snapshots, and answers a concrete question ('how long has this edge existed and is it shrinking?'). It distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence/decay rather than current edge values.

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

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

The description clearly establishes when to use the tool: when an agent needs edge longevity, trend, and decay rather than just current edge values. It even explains why this matters ('a fresh wide edge and a 3-week-old wide edge are different trades'). However, it never explicitly names alternatives or states when not to use it, so it falls just short of full explicit routing 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses operational behavior: it walks the order book, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), models depth-crossing cost, and explicitly states fees are NOT modelled (gross vs net). It also warns about forced_directional_risk and thin books, adding substantial behavioral context.

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

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

The description is long but well-structured, with clear sections (SINGLE-MARKET, BASKET, fees note) and no redundant filler. It is front-loaded with the core purpose and then provides mode-specific details. While it could be trimmed slightly, the length is justified by the tool's complexity and the need to convey both modes and caveats.

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 cover return values, which it does thoroughly (listing all fields for both modes). It also explains the fee implication and when the tool is applicable, making it complete for an agent to call correctly without needing to inspect schemas or other sources.

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 all 4 parameters, but the description adds meaning beyond that: it explains the difference between single-market and basket interpretation of size_usd (max spend vs settlement notional), the auto-selection for side in basket mode, and the format of market/event (slug or URL). This enriches the schema's bare descriptions.

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

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

The description states a specific verb+resource ('Realizable-vs-theoretical edge check against live CLOB order-book depth') and clearly distinguishes between single-market and basket modes. It explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) and tells the agent when to use this tool over them, making purpose unambiguous.

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

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

It 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 the rationale (theoretical overround not capturable, partial fills create unhedged positions). It also explains how to choose between single-market and basket modes based on input types.

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

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

The description is exceptionally transparent about behavioral nuances: it discloses the two modes, the matching logic, the safety fields and their meanings, fee calculation details with verification dates, resolution equivalence methodology, and historical changes that affect interpretation (e.g., fleet #1927 correcting gas modeling). It also explicitly states limitations (spread-crossing cost not modeled, no live order book). Annotations already indicate read-only/idempotent, and the description adds extensive context without contradicting them.

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

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

The description is extremely verbose—it reads as a full technical spec with historical fleet notes and extensive caveats. While it is front-loaded with the core purpose and organized with section headers, its length (several hundred words) is far from concise. Every sentence adds information, but the sheer volume makes it heavy for an agent to parse. A more distilled version would be more efficient.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It explains all response fields (spread, compatibility_warning, fees, resolution_audit, etc.), defines every safety code, describes fee formulas with verification dates, and covers both modes and edge cases. An agent has everything needed to invoke the tool correctly and interpret results, even without an output schema.

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

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

Although the schema already provides 100% coverage of parameter descriptions, the tool description adds substantial semantic value: it explains the topic aliases and keywords, how resolution.topic_matched_by distinguishes exact/alias from phrase/token guesses, and the behavior of explicit overrides. It also clarifies that unresolvable topics return a specific error rather than falling back. This goes well beyond the schema's baseline.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly defines the tool's function and distinguishes it from single-venue tools by its focus on cross-venue comparison. The two operational modes are explicitly described, leaving no ambiguity about what the tool does.

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

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

The description explains when to use the tool (for cross-venue spread analysis) and details both usage modes with examples. It provides clear guidance on how to interpret results and warns that 'pre-mapped ≠ tradeable'. It also points to alternative tools like resolution_audit/resolution_diff for specific needs. However, it does not explicitly state when NOT to use this tool in favor of siblings, so it stops short of a full when-not/alternatives matrix.

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

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

Annotations already convey read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond those: the omit-key listing mode, the scoping of memory to an identifier, and the relationship to remember/forget. It does not describe missing-key or empty-result behavior, but annotations lower the burden.

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

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

The description is three sentences with no filler. It front-loads the core behavior, then adds use-case context, then scoping and sibling-tool relationships. Every sentence contributes useful 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 optional-parameter lookup tool with read-only and idempotent annotations, the description is complete: it covers both invocation modes, gives realistic use examples, explains scoping, and points to related tools. No critical information is missing for an agent to call it correctly.

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

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

The input schema already fully documents the single optional key parameter, including the omit-to-list behavior, so schema coverage is 100%. The description reinforces this but adds little semantic detail beyond what the schema states, aside from concrete examples of what kind of values are stored.

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 leads with a crisp verb and object combination: 'Retrieve a value previously saved via remember, or list all saved keys.' It also names the sibling memory tools (remember/forget) and distinguishes this tool by its read-only lookup role.

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 clearly explains when to use the tool: to look up stored context without recomputing it. It also points to siblings by saying 'Pair with remember to save, forget to delete,' though it stops short of an explicit if-then exclusion like 'do not use for saving.'

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

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

Annotations already establish readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds genuinely useful behavioral context beyond that: return fields (source, citation_uri, raw payload), the mark_read side effect that affects subsequent calls, and polling suitability. No contradiction with annotations is present.

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 dense sentences, each earning its place: the opening states the core action, the second details return contents, the third covers filtering and mark_read semantics, and the fourth mentions polling and an alternative endpoint. It is front-loaded and contains no filler.

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

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

Without an output schema, the description compensates by describing the return payload. It also covers filtering, mark_read behavior, polling, and alternative access. Minor omissions like limit defaults and unread_only details are already present in the schema, so the description is nearly complete for a read-oriented tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by giving a concrete type example ('sec_8k'), specifying ISO format for since, and explaining the consequence of mark_read ('so the next call only shows newer ones'). This exceeds what the schema descriptions alone provide.

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 and resource ('Pull fired events from your subscription feed') and clarifies it returns recent alerts from the evaluator's persisted feed. It is conceptually distinct from siblings like list_subscriptions or recent_changes, but it never explicitly names or differentiates those alternative tools, so it falls short of a 5.

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

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

The description gives clear usage context: it says polling works fine, explains the mark_read pattern for advancing to newer events, and points to the GET registry.pipeworx.io/alerts.json endpoint as an alternative for scripts and dashboards. However, it does not explicitly contrast with sibling MCP tools, so it lacks full when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it fans out to multiple sources in parallel, has a GDELT→GNews fallback, notes the PatentsView API sunset causing soft-fail, and describes the return shape (changes[] grouped by source, total_changes, pipeworx:// citation URIs). It doesn't detail pagination or rate limits, but the disclosed behavior is substantial.

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

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

The description is dense but well-organized: example queries first, then the core function, then source details, then parameter formats, then return shape, then the sibling distinction. Every sentence adds information, though the source-fallback details make it slightly long. The front-loading of example queries is effective for an agent scanning for intent.

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 read-only, idempotent tool with 100% schema coverage and no output schema, the description covers the main things an agent needs: what it does, what inputs look like, what sources it hits, and when to use the sibling instead. It doesn't specify pagination or exact output field types, but the return shape is summarized and the annotations cover safety. A small gap is not explaining how 'changes' are structured beyond grouping by source, but this is acceptable given the tool's complexity.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description adds meaning by explaining the `since` accepted formats (ISO date or relative shorthand) and giving typical usage ('30d' or '1m'), plus clarifying that `value` can be a ticker or zero-padded CIK. This goes beyond the schema's descriptions and helps an agent construct valid calls.

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 natural-language queries ('What's new with X', 'latest on Y') and then states the exact function: a change feed for a company over a time window in one parallel call. It names the data sources (SEC EDGAR, GDELT→GNews, USPTO) and explicitly contrasts with entity_profile, so an agent can distinguish it from the closest sibling without opening schemas.

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 via example queries, specifies the `since` window formats, and states the alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also discloses fallback behavior (GDELT preferred, GNews on rate-limit/5xx) and the USPTO soft-fail, which helps an agent decide whether this tool fits the task.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive, but the description adds far more: ≤60s TTL caching, no push/webhook, empty-window error behavior, court category always empty with unsupported:true, and the honesty contract that releases with zero matched markets are returned rather than dropped. Match labels (true/likely/unclear) and matched_by are disclosed so callers can judge match quality.

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

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

The description is long but well-organized into labeled sections (CATEGORIES, MATCHING AND ITS HONESTY CONTRACT) and front-loads the core purpose. Some clauses are defensive or verbose, such as 'which is an accurate answer, not a bug', but they prevent false bug reports; the density is justified for a multi-source tool with several behavioral caveats.

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 every behavioral edge case a caller needs: category semantics, empty-window error behavior, match confidence labels, timestamp conventions, and how to verify a match before trusting it. Even with an output schema present, the description adds return-value semantics (markets:[], resolves_on_this_release, matched_by, scheduled_at) and is complete for a complex tool.

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

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

Although the schema covers both parameters at 100%, the description adds rich semantic context: what each category means and which underlying source feeds it (fred_release_dates, fomc_calendar, pdufa_catalysts, federal-register), the hours cap and default, and the clock-time conventions for econ vs fed vs FDA/SEC dates. This transforms how an agent should set categories and hours.

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 a specific verb and resource: JOIN of the official release calendar (econ, FOMC, FDA, SEC) against live Polymarket/Kalshi markets, returning scheduled releases in the next N hours and which live markets resolve on them. The 'POSITIONING tool, not a speed product' framing further distinguishes it from arbitrage/spread tools among the siblings.

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

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

Explicitly says when not to use it ('do not use this to try to beat a release') and names concrete alternatives: call resolution_audit / resolution_diff before sizing anything. It also gives category-selection guidance and warns that a short window should be widened rather than assumed empty.

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 idempotentHint=true and destructiveHint=false, and the description adds meaningful context: key-value storage scoped by identifier, persistent memory for authenticated users, and 24-hour retention for anonymous sessions. This goes beyond the annotations by explaining the actual storage semantics and lifetime.

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

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

Four sentences, each earning its place: what it does, when to use it, storage semantics, and sibling routing. The most important information is front-loaded, and there is zero 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?

Complete for a simple two-parameter key-value store. The description covers purpose, usage, storage behavior, and related tools. No output schema exists, but the operation is simple enough that return value details are not critical 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 description coverage is 100%, so the schema already documents both parameters. The description adds the key-value pair framing and examples of keys, but doesn't add substantial meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Save') and resource ('data the agent will need to reuse later'), and clearly distinguishes it from siblings by naming recall and forget as complementary operations. It also gives concrete examples of what to store, making the tool's purpose immediately actionable.

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

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

The description explicitly says when to use it ('when you discover something worth carrying forward') and provides examples of the kinds of information to save. It also names the sibling tools for related operations ('Pair with recall to retrieve later, forget to delete'), giving clear routing guidance.

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

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

Annotations already mark this as readOnly, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: deterministic regex + vocabulary with no LLM pass, confidence:'low' for unusual clauses, reuse of bet_research's cancellation_rule detector, and the known gap of returning evidence_standard:'unspecified' rather than guessing. No contradiction with annotations.

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

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

The description is long but dense and front-loaded: the first sentence carries the core purpose and output fields, then input semantics, usage context, companion tool, and known gap follow in logical order. Every sentence contributes necessary information with no filler.

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

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

With no output schema, the description carries the full burden of explaining what the agent gets back. It enumerates the extracted fields, the confidence fallback, the evidence_standard enum values, void_handling reuse, and the known limitation, making the tool fully callable without guessing.

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

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

Schema coverage is 100%, and the description still adds meaningful value: concrete examples for Polymarket slugs and Kalshi tickers, clarification that Kalshi event tickers fall back to a representative market, and why that fallback is safe. This goes well beyond the bare schema properties.

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: 'Extract the settlement clause of a single Polymarket or Kalshi market.' It enumerates exactly which attributes are extracted (source, clock time, precision, evidence standard, void handling) and explicitly distinguishes this tool from resolution_diff and polymarket_kalshi_spread, making sibling differentiation 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?

It explicitly states when to use the tool: before treating a polymarket_kalshi_spread row as real arbitrage. It also names the companion tool resolution_diff for comparing two markets, and explains the Kalshi event-ticker fallback behavior, leaving no ambiguity about when or how to invoke it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=falsechers. The description adds important behavioral nuance beyond those hints: it explains the three-way equivalence outcome, the confidence threshold for comparing, and the specific-versus-generic source rule that prevents false conflicts. It also discloses that the tool internally runs resolution_audit, which is useful to set expectations.

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

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

The description is information-dense and front-loaded with the core purpose, but it is long and contains a lengthy parenthetical example and an extended heuristic explanation. Every point is relevant, but the phrasing is verbose and could be tightened or restructured with bullet-like separators. It earns its content but sacrifices 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?

There is no output schema, so the description carries the burden of explaining return values, and it does so thoroughly: it explains the possible values of `equivalent` (true/false/unclear), mentions `differing_fields`, and instructs the caller to read `raw_clause` in unclear cases. It also covers the non-conflict heuristic. The only gap is not fully specifying the entire output structure or exact field locations, but the guidance is sufficient for the agent to decide when to call 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 description coverage is 100% with both parameters described as 'First market to compare' and 'Second market to compare.' The description adds that they are markets on either Polymarket or Kalshi and that the tool runs resolution_audit on both sides, which slightly clarifies roles. However, it does not add meaningful detail beyond the schema's enum and nested-object definitions, so a 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: 'Field-by-field diff of TWO markets' settlement clauses.' It clearly states that the tool runs resolution_audit on both sides and compares source, settle time, precision, and evidence standard, which differentiates it from the sibling resolution_audit. The three-way return value is also summarized, leaving no ambiguity about the tool's core 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?

The description gives explicit usage context: 'Use this before sizing a polymarket_kalshi_spread pair as a real cross-venue arb, or standalone to sanity-check any two markets you suspect settle on different things.' This clearly states when to use the tool. It does not, however, explicitly name alternatives or say when not to use it, so it stops short of a full when/when-not guide.

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

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

Discloses far more than the annotations: source systems (EDGAR, GLEIF, OpenFIGI, RxNorm), graceful degradation when enrichment sources fail, disambiguation behavior via figi_candidates, explicit unresolved identifiers, and cascade of multiple lookups. These details go well beyond readOnlyHint/openWorldHint/idempotentHint, and 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?

The description is front-loaded with examples and the 'Use FIRST' directive, and is organized into clear sections. It is dense and heavily parenthetical, with some explanatory asides that could be trimmed, so it is not a model of brevity but every major section contributes.

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

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

For a two-parameter lookup tool with no output schema, this is unusually complete: it covers supported types, input variants, fallback behavior, edge cases, and what is returned when resolution is ambiguous or fails. An agent has enough context to decide when to call it and what to expect back.

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

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

The schema already documents the basic value forms (ticker, CIK, name, drug brand/generic) and the entity-name-only warning, so the baseline is high. The description adds genuinely useful parameter semantics beyond the schema: ISIN as an accepted input, exact-ticker-map versus name-search matching, and ambiguity handling for names that match multiple instruments.

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 a specific verb ('resolve') and resource ('user-spoken NAME to canonical/official identifiers'), and enumerates concrete example phrasings plus the two supported entity types. It clearly separates the tool from siblings by framing its output as IDs that other tools require as input, so an agent knows when this is the right lookup.

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 'Use FIRST whenever you have a name but need an ID', which is a clear trigger condition, and gives many natural-language examples that map to calls. It does not name sibling tools as alternatives or give explicit when-not-to-use cases, so it stops short of a perfect 5.

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

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

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint, so the description only needs to add context. It explains the mechanism (probes each entity with ai_visibility_check) and the output (ranked list with score, confidence, signal density), which is useful but not extensive. No contradictions with annotations.

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

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

Three sentences with no filler. The core purpose is front-loaded ('Compare AI visibility across multiple entities side-by-side'), followed by mechanism and use case. 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?

Given the schema documents all parameters and the description explains the output format and purpose, the tool is adequately described. Minor details like exact ranking criteria are not essential for correct invocation. The description is complete enough for an agent to understand what the tool does and when to use 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 description covers all 4 parameters at 100%, so the baseline is 3. The description adds no extra parameter semantics beyond what the schema already explains, so no additional value is provided.

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

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

The description clearly states the verb 'Compare' and the resource 'AI visibility across multiple entities', and explicitly differentiates from siblings by mentioning it uses ai_visibility_check and is for competitive audits. It is specific and unambiguous.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and a sample question ('does Claude know about us as well as our competitors?'). It does not explicitly list exclusions or alternative tools, but the purpose is distinct enough that an agent can infer when to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context beyond annotations: it explains partial failure handling, the 5-30s first-measurement latency on bundlephobia, and that sources_failed will list timeouts while other data still returns. 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 dense but efficient, opening with the core composite purpose, then listing return fields, then noting ecosystem scope and failure behavior. Every sentence earns its place; no fluff or redundancy, and the most critical usage guidance 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 thoroughly enumerates the return structure (summary block fields, per-advisory detail, links, alternative versions) and error behavior. It also covers latency expectations and scope limitations, leaving no gap for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents both 'package' and 'version' including defaults and scoped package acceptance. The description does not add any additional parameter semantics beyond what the schema provides; the baseline of 3 applies since the schema carries the full burden.

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: a composite check for 'should I add this npm package' covering license, advisories, version history, and bundle size via deps.dev and bundlephobia. It specifies the resource (npm packages) and the exact questions it answers, distinguishing it from siblings like scan_competitor_ai_presence and the deps.dev:version fallback.

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: whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also provides an exclusion: NPM ecosystem only in v1, with PyPI/Maven/Cargo/Go falling under deps.dev:version directly, giving a clear alternative.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap, truncation flagging, and character offsets for verification. This goes beyond the annotations and helps the agent predict output characteristics.

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

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

The description is dense but every sentence earns its place: it states the core function, the use case, the pairing with a sibling, the embedding/algorithm details, and the input cap. It is front-loaded with the most important information and has no filler.

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

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

For a read-only search tool with 100% schema coverage and no output schema, the description is complete. It explains the return characteristics (top-N passages, offsets, similarity scores), the algorithm, the size cap, and the truncation behavior. An agent has everything needed to decide when to call it and what to expect.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds context about the 200K char cap and the nature of the query, but it doesn't add much beyond the schema. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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: semantic search inside a fetched record, with a clear contrast to alternatives. It names the sibling ask_pipeworx_grounded and explains the pairing, so an agent can distinguish this tool from the broader ask_pipeworx family without opening schemas.

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 when to use it: when the record is too big to fit in the prompt, and it names the alternative ask_pipeworx_grounded for grounding over relevant passages. It also gives a concrete workflow: fetch with the gateway, then search within. This is explicit usage guidance with an alternative.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses auth needs, account-type persistence limits, an SMS phone-verification prerequisite, and a 10/day rate cap. No contradiction with annotations; it enriches them with concrete operational constraints.

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 first sentence carries the core purpose, and each following sentence adds operational detail (account requirement, per-type params, delivery rules). It is dense but not bloated, with only mild redundancy against the schema's parameter descriptions and a 'Supported types' list that omits two of the five enum values.

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 high-complexity tool — five subscription types, three delivery channels, no output schema — and the description covers the essential return value, preconditions, and delivery constraints. Remaining gaps (behavior for patent_grant/clinical_trial, duplicate-subscription behavior) are minor because the schema documents all parameters and the idempotentHint annotation signals retry safety.

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

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

Schema coverage is 100% — the schema already documents all three parameters, including type-specific filter shapes and webhook signing behavior. The description adds interpretive value on top, e.g. items:['5.02'] means officer change and concrete delivery examples, earning one point above the baseline 3.

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

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

States a specific verb and resource ('Create a proactive monitoring subscription to a live-data event stream') and names the returned artifact ('Returns the new subscription id'). The creation focus clearly separates it from lifecycle siblings list_subscriptions and unsubscribe, and from recent_alerts which consumes the feed.

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

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

Gives clear context for use: proactive monitoring of live data, plus a hard precondition ('Requires a Pipeworx OAuth account — anonymous + BYO cannot persist subscriptions'). It also routes feed consumption to the sibling recent_alerts and the public URL, but never explicitly states when not to subscribe or contrasts with list_subscriptions/unsubscribe.

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 signal read-only, open-world, idempotent, non-destructive behavior, so the bar is lower. The description adds useful behavioral context: it is the onboarding entry point, it returns category-bucketed examples with tool+argument shapes, and it is drawn from the live catalog of thousands of tools. No contradiction with annotations.

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

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

The description is longer than average because it lists many user-facing question phrasings and category examples, but this is justified for an onboarding tool. It is front-loaded with the core purpose and then gives focused usage details, though a few phrases are redundant with 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?

The description is complete for a tool with one optional parameter and no output schema: it explains what the tool returns, how to do a broad query versus a focused query, and when to use it. Minor gaps such as response formatting details are not critical given the tool's purpose.

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

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

Schema coverage is 100%, and the schema already documents the optional `topic` parameter and its allowed values. The description adds examples and clarifies the no-argument behavior, but this mostly restates what the schema already provides rather than adding substantive new 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 what the tool does: returns category-bucketed example questions with the exact tool and argument shape from the live catalog. It positions itself as the onboarding entry point and distinguishes its use from other tools by saying 'Use this FIRST when you do not yet know what Pipeworx can do for you.'

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: when the agent doesn't know what Pipeworx can do or wants to learn how to call meta-tools. It also explains the tradeoff between calling with no arguments for the full spread versus passing a topic to focus, but it does not explicitly name alternatives or exclusion criteria.

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

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

Discloses critical behavioral traits beyond annotations: ownership enforcement, soft-delete behavior ('deactivated not deleted'), and the consequence that historical events remain available via recent_alerts. This adds real context beyond the readOnlyHint/destructiveHint annotations.

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

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

Two sentences, front-loaded with the action, and no filler. The ownership constraint and deactivation detail each earn their place without bloating the definition.

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 single-parameter mutation tool with annotations covering safety, the description is fully sufficient. It covers prerequisites, side effects, and downstream visibility of historical data, leaving nothing essential missing.

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

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

The input schema already fully describes the single parameter, including its type and origin ('Subscription id (uuid) returned by subscribe'). The description adds no extra parameter-level meaning, so the baseline 3 applies.

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

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

The description leads with a specific verb and resource: 'Cancel a subscription by id.' It clearly distinguishes from siblings like subscribe and list_subscriptions by naming the action of cancellation, and further clarifies the scope with ownership enforcement.

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 use: you must have a subscription id, and you can only cancel your own subscriptions. It does not explicitly name alternatives, but the use case is unambiguous and no exclusions are needed.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive. The description adds significant behavioral context: the distinction between 'could_not_verify' (check did not happen) and 'unsupported' (no source exists), the exact percent-delta math for financial claims, and the return structure. It even warns callers not to treat could_not_verify as evidence. This goes far beyond annotations.

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

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

The description is longer than ideal, but every sentence carries weight: trigger phrases, dual-path explanation, verdict list, error semantics, and the efficiency gain. It front-loads the purpose and trigger phrases, and the critical 'IMPORTANT for callers' note is placed prominently. Slight redundancy in the phrase list could be trimmed, but it's well-structured.

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

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

Given the tool's complexity (two pipelines, six verdicts, error handling), the description covers everything an agent needs: when to use, what happens under the hood, what it returns, and how to interpret ambiguous outcomes. It even explains why it replaces multiple sequential calls. No gaps 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% for both parameters. The description adds value by explaining tolerance_pct's role in hallucination detection (set 1–2 for strict checking) and noting the default is implied by wording capped at 5. It also provides a concrete example of the claim parameter. This goes beyond the schema's bare descriptions.

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

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

The description clearly states it performs natural-language claim verification with specific trigger phrases ('fact check', 'verify the claim that...'), and explicitly defines its scope: company-financial claims via SEC EDGAR/XBRL fast path, all other claims via grounded pipeline. It distinguishes itself from siblings by naming the exact function and output verdict types.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the two routing paths (structured vs grounded) and mentions it replaces 4–6 sequential calls, making it clear this is the go-to tool for claim verification without ambiguity.

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