Openfda

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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds substantial behavioral context: it routes to 6,426 tools across 1,679 sources, fills arguments automatically, returns stable pipeworx:// citation URIs, and works on every tier with a single fast call. This goes well beyond the annotations and clarifies what the agent can expect.

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. It front-loads the critical instruction ('PREFER OVER WEB SEARCH'), then lists domains, gives examples, and provides routing guidance to alternatives. It is structured as a clear priority statement followed by justifications and exclusions, with zero redundancy.

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

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

For a tool that routes to thousands of sources, the description is remarkably complete. It states the input (natural language question), the output (structured answer with citation URIs), the scope (factual questions about real-world entities), and the alternatives for edge cases. Even though there is no output schema, the description tells the agent exactly what to expect, covering all needed information 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?

The schema has 8 parameters, all aliases for the question, and schema description coverage is 100% (each alias is described). The description adds value by providing concrete examples of valid questions (e.g., 'current US unemployment rate', 'Apple's latest 10-K') and clarifying the natural-language scope, which helps the agent format the parameter correctly. However, the schema already states 'Your question or request in natural language', so the added value is moderate.

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 clear verb and resource: it routes factual questions to authoritative sources and returns structured answers with citations. It lists many domains (SEC, FDA, FRED, etc.) and explicitly differentiates from sibling tools like ask_pipeworx_grounded and deep_research, making it easy for an agent to select the right tool without ambiguity.

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

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

The description is explicit about when to use this tool: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and provides concrete step-up conditions for ask_pipeworx_grounded (hallucination-resistant single answer) and deep_research (broad/multi-part questions). It also mentions a free tier limitation, giving clear decision rules.

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, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it discloses that this is an experimental edge with candidate routing improvements that may change behavior live, that it currently matches the stable router exactly, and that it falls back to nothing (it is a full working router). This is meaningful transparency about the experimental nature and current equivalence.

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 dense paragraph that front-loads the key facts: beta status, identical to ask_pipeworx, current state, and usage instruction. It is somewhat long but every sentence earns its place by conveying the experimental status, the current equivalence, and the routing comparison purpose. The structure could be slightly improved with clearer separation, but it is efficient.

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

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

For a universal router with no output schema and a single required string parameter, the description is largely complete. It explains what the tool does, how it differs from the stable sibling, its current state, and that it is a full working router. The only minor gap is that it doesn't describe the response shape, but since it explicitly states the response shape is identical to ask_pipeworx, an agent can infer it from the sibling. This is adequate for the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters, including the primary 'question' parameter and its 7 aliases. The description adds no parameter-specific semantics beyond what the schema provides, but it doesn't need to since the schema is complete. Baseline 3 is appropriate.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same 6,426 tools, arguments, and response shape. It explicitly distinguishes itself from the stable ask_pipeworx by noting candidate routing improvements may be active, and it names the sibling ask_pipeworx directly. The verb 'ask' plus the resource 'pipeworx beta' 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 explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router to decide what merges. It also clarifies the current state (no candidate active, matches ask_pipeworx exactly), giving the agent a clear decision rule for when to select this tool over the stable 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 already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: it returns a structured refusal with specific refusal_reason values, explains the extraction is limited to tool result content, and discloses the extra LLM call cost. It also describes the success return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}). This goes well beyond the annotations.

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

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

The description is dense but well-organized: it front-loads the core purpose, then explains the mechanism, return shape, refusal behavior, and usage guidance. Every sentence earns its place, though it is somewhat long. The structure is logical and scannable, with the key differentiator (grounded extraction) stated early.

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

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

For a tool with no output schema, the description fully compensates by documenting the success return shape, the refusal shape, and all possible refusal_reason values. It also covers cost, routing behavior, and when to use it. An agent has everything needed to invoke it correctly and interpret the result.

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

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

Schema description coverage is 100% and the schema documents the 'question' parameter plus seven aliases. The description adds context that the question is in natural language and that the tool routes it to the right tool from 6,426 sources, which helps the agent understand what kind of input is expected. However, the description doesn't add much beyond the schema's alias documentation, so a 4 is appropriate rather than 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 clearly states this is a hallucination-resistant answer mode for high-stakes reads, with a specific verb ('extracts the answer using ONLY what the tool result contains') and resource (same routing as ask_pipeworx). It distinguishes itself from ask_pipeworx by emphasizing the grounded extraction and refusal behavior, making it easy for an agent to differentiate.

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 an answer will be quoted, cited, or acted on, and the agent must not invent facts' and lists example domains (financial verdicts, legal claims, medical lookups, public statements). It also names the alternative (ask_pipeworx) and states the cost tradeoff ('Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups'). This is exemplary when-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 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?

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds rich behavior: parallel decomposition, gaps[], contradictions[], hop field, citation_uri, semantic excerpting, expected latency (15-90s). It explains exactly what the user gets and limitations. No contradiction with annotations.

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

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

Long but every sentence earns its place: account gate, core purpose, sibling comparison, depth behavior, citations, gaps, latency. Front-loaded with critical account requirement and core capability, then 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?

Despite no output schema, the description fully explains the findings packet, gaps, contradictions, hop, citation_uri, and limitations. Covers all necessary information for an agent to decide and invoke correctly.

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

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

Schema coverage is 100% with detailed descriptions for question and depth. The description adds context beyond the schema (latency, gap recovery, contradictions) and clarifies aliases. It enriches but doesn't duplicate; slightly 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?

The description states a specific verb+resource ('grounded multi-source research across Pipeworx's 1679 STRUCTURED data sources') and clearly distinguishes it from siblings like ask_pipeworx. It names the alternatives and conditions, so an agent can differentiate 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?

Explicitly states when to use (broad/multi-part questions over structured data) and when not to (breaking news, single lookup), naming the alternative (ask_pipeworx) and its route to live news APIs. Also covers depth tiers and account requirements.

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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds the caveat that submission codes require interpretation and don't establish approval scope/exclusivity/marketing, which is valuable behavioral context beyond annotations.

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

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

Two sentences, purpose-first, with no wasted words. The regulatory caveat is useful and earns its place.

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

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

For a one-parameter read-only tool with thorough annotations and no output schema, the description is sufficient. It explains what the tool returns and includes a critical interpretation warning, though it doesn't detail the return structure or pagination, which is acceptable given the lack of 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?

The single parameter `application_number` is fully described in the schema with format 'NDA, ANDA, or BLA followed by digits.' The description repeats the application types but adds no additional syntax or semantics beyond the schema, so baseline 3 applies.

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

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

The description clearly states the tool retrieves a single Drugs@FDA application (NDA, ANDA, or BLA) and returns products plus chronological submission-action history. This distinguishes it from sibling tools like fda_drug_approvals or fda_crl_detail, which address different aspects.

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 context about regulatory interpretation but does not explicitly state when to use this over alternatives or list exclusions. The use case is implied as retrieving application history, but no sibling alternatives are mentioned, so guidance is limited.

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, and the description adds significant context beyond that. It explains why the tool exists (no FDA company-ID field, free-text sponsor_name variants), how it resolves identities (SEC lookup plus distinctive token matching), and what it returns (combined application list plus sponsor_name_forms).

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

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

The description is longer than average but front-loaded with the core action and every sentence earns its place. The Eli Lilly spelling example is not padding; it concretely motivates the identity-matching problem the tool solves.

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 what the tool does, why it is necessary, when to use it instead of fda_drug_approvals, how it matches sponsor names, and what the high-level return shape is. With both parameters fully documented in the schema and safety expressed in annotations, nothing needed to select or 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?

The schema already documents both parameters fully, so the baseline is 3. The description adds useful parameter-level guidance by explaining that cik_or_ticker is resolved via SEC as the same identity used by the edgar pack and by telling the agent to pass a parent CIK for subsidiaries that are not themselves SEC-listed.

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 specific verb and resource: 'Find ALL Drugs@FDA applications for a company by SEC CIK, ticker, or company name.' It also names the core value proposition — removing the need to know FDA sponsor_name spelling — and explicitly contrasts itself with fda_drug_approvals, so an agent can distinguish it from siblings.

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

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

This is an explicit routing rule: 'Use this INSTEAD of guessing sponsor_name strings for fda_drug_approvals when you have (or can resolve) the company's CIK/ticker.' It also gives a concrete alternative for subsidiaries or unlisted operating names: resolve to the parent first with edgar's sponsor_to_filer, then pass that CIK.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds value by specifying the exact return content (approval_status, letter metadata, excerpt, document URL) and the default filtering behavior, 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?

The description is a single, well-structured sentence that front-loads the action and resource, then lists key features. It contains no redundant words and efficiently conveys all necessary information.

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

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

Despite having no output schema, the description clearly states what is returned (approval_status, metadata, excerpt, URL). It also covers the default filtering and the optional inclusion of other letter types. For a search tool with 8 parameters, the description provides sufficient context for an agent to understand when and how 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?

All 8 parameters have descriptions in the schema (100% coverage), so the schema already documents each parameter's meaning. The description does not add further semantic detail beyond the schema, such as syntax examples or format constraints, so it does not improve parameter understanding. Baseline score of 3 is appropriate.

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

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

The description clearly states the action (search) and resource (FDA Complete Response Letters), and distinguishes it from sibling tools like fda_warning_letters or fda_drug_approvals by specifying the document type and default filtering. The verb 'Search' combined with the resource name makes the purpose unambiguous.

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

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

The description explains the default behavior (only COMPLETE RESPONSE type) and the option to include other letter types, which guides usage. However, it does not explicitly state when to use this tool versus the sibling fda_crl_detail tool (likely for individual letter details), missing an opportunity to clarify the choice between search and detail retrieval.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses that it returns letter text and URL, and notes that confidential material may be redacted. This adds useful behavioral context without contradicting annotations.

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

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

Three sentences, each informative: purpose, output, and caveat. Front-loaded with the core action, no unnecessary words.

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

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

For a retrieval tool with 2 parameters and no output schema, the description covers what is returned (text, URL) and potential redaction. No gaps 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 parameters are fully described in the schema. The description adds minimal extra meaning beyond stating the two parameters and the purpose of letter_date for multiple CRLs, but does not enhance parameter understanding significantly.

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 ('Retrieve') and resource ('one FDA Complete Response Letter') with clear parameters (application number, optionally letter date). It distinguishes from siblings like fda_complete_response_letters (plural) and other FDA tools by focusing on a single letter retrieval.

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 indicates when to use this tool (when you need a specific letter by application number). However, it does not explicitly mention when not to use it or point to alternatives, such as fda_complete_response_letters for listing.

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 numerous non-obvious behaviors beyond the readOnly/idempotent annotations: uppercase-only name matching with silent 0-result failures, indication phrases being silently ignored, application_type returning 0, the native sort being unreliable (reads any submission in history), and the 100-row page cap. None of this contradicts the annotations; it materially extends 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?

Long (~220 words) but unusually dense — nearly every sentence carries a distinct operational fact with zero filler. Core purpose is front-loaded before caveats. Slight redundancy with the already-excellent schema descriptions (uppercase requirement, sort rationale appear in both) prevents a 5.

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

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

For a tool with high behavioral quirkiness, this is complete: it names all three query modes, what the response contains, the ANDA/NDA interpretation rule, the sibling for condition queries, and the pagination/sorting caveats. Output schema exists, so return-value explanation is not the description's job. 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?

Schema coverage is 100%, so baseline is 3. The description adds strategic value beyond the schema: the application_type trap, the generic_name field trap, and the rationale for pairing skip with sort on large result sets. Some content (uppercase warning, skip behavior) duplicates the rich schema descriptions, so the added increment is real but not maximal.

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

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

Opens with a precise verb+resource statement: "Find FDA-approved drugs by brand name, active ingredient, or application number." It explicitly differentiates from fda_drug_labels by stating this endpoint has no indication/disease field, and clarifies its own output scope (approval status, sponsor, application number, details). The ANDA/NDA distinction further sharpens what the tool returns.

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 and when-not-to-use guidance: use active ingredient search for generics, use fda_drug_labels for condition-based queries, never use application_type, never use openfda.generic_name. It also tells the agent when to add skip (large totals) and sort (genuinely newest-first), naming the exact alternative tool and the exact conditions that route to 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 readOnly, idempotent, and non-destructive, so the barrier is higher, but the description adds valuable behavioral context: returns specific fields, retries natural wording against MedDRA preferred-term order before returning empty, and explicitly cautions that FAERS reports do not establish incidence or causality. This goes well beyond what annotations provide and contains no contradiction.

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

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

Four short sentences, each with distinct value: purpose, return contents, retry behavior, and a necessary caveat. No fluff or redundancy; the most important action 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?

Given the output schema exists and annotations are rich, the description provides enough context on scope, results, retry behavior, and limitations. An agent can select and invoke the tool with confidence, and the schema fills in query syntax details.

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

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

Schema description coverage is 100%, with detailed guidance and examples in the query parameter itself, so the schema carries the load. The tool description only gives high-level search dimensions and does not add parameter-level syntax or additional semantics beyond the schema, which fits 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?

The description states a specific verb ('Search'), resource ('FAERS adverse event reports'), and search dimensions (drug name, MedDRA reaction term, date range), making the tool's function clear. It does not explicitly differentiate itself from sibling FAERS tools like fda_event_counts or fda_faers_reaction_profile, so it stops 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 intended use is implied: an agent needing adverse event report counts, reaction types, seriousness, or dates would infer this tool is relevant. However, there is no explicit guidance on when to choose this tool over the many FAERS-related siblings, nor exclusions for cases better served by fda_event_counts or fda_faers_signal_summary.

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

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

Even with readOnlyHint and openWorldHint present, the description adds real behavioral context: text fields are 'capped', 'set_id preserved for out-of-band full-label fetch', and label publication trails approval by weeks. These are not derivable from annotations and help set accurate 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?

Four dense sentences with no filler: purpose, differentiation, return fields with caveats, and data lag. The core scope is front-loaded in the first sentence and every subsequent 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?

Combined with a fully covered schema, an output schema, and safety annotations, the description covers purpose, query syntax, return contents, field caps, and freshness caveat. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a query pattern not shown in schema examples: searching via indications_and_usage:'rheumatoid arthritis'. This gives field-level guidance beyond the schema's generic 'OpenFDA search query' text.

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

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

Opens with 'Get FDA drug labeling (SPL) by drug name OR by INDICATION' — a specific verb and resource. It explicitly differentiates from the approvals sibling: 'which the drugsfda approvals endpoint does NOT carry', making its unique role clear among the many FDA 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?

Positions the tool as 'the tool for what drugs are approved to treat <condition>' and states the approvals endpoint lacks indications_and_usage, providing an explicit when-and-when-not. The closing lag note tells agents when the tool may not yet have a label.

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

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

Beyond the readOnly/idempotent annotations, the description discloses important behavioral nuances: the ALL-terms-first-then-ANY fallback, the match_mode indicator in responses, and the free-narrative nature of recall reasons. These details materially change how an agent should interpret results and are not available from 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 first sentence states what the tool does and returns; the second warns about match interpretation; the third gives a practical search tip. Each sentence earns its place and 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?

With a full input schema, an output schema, and strong annotations, the description fills the remaining gaps: query fallback semantics, ambiguity handling, and domain-specific search strategy. Pagination and limits are already documented in the schema, so their omission is not a gap.

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 explaining the multi-word matching fallback and advising users to search for the contaminant rather than the harm. This helps agents craft better queries than the raw schema examples alone would suggest.

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 ('Search'), the resource ('FDA drug recalls and enforcement actions'), and the search keys ('by drug name or reason'), plus the returned fields. It is distinct from siblings like fda_food_recalls by subject matter, though it does not explicitly name an alternative or contrast itself with any specific sibling.

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

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

The description gives strong guidance on how to search effectively: multi-word queries fall back to ANY-term matching, match_mode disambiguates, and users should search for contaminants rather than symptom names. However, it never directly addresses when to choose this tool over siblings like fda_food_recalls or fda_warning_letters; the usage context is implied rather than explicit.

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 valuable context: it warns about sparse upstream data and clarifies it is not real-time local inventory. This goes beyond annotations to set realistic 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 two sentences with no unnecessary words. The first sentence states the core function and search methods; the second clarifies return data and disclaimers. It is front-loaded 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?

Given no output schema, the description adequately explains return values ('national supply records and available FDA dates') and notes data sparseness. It does not detail pagination or exact date fields, but for a search tool with comprehensive schema and annotations, this is sufficient.

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

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

Schema coverage is 100% with descriptive parameter descriptions. The description summarizes the filters ('by generic or brand name, manufacturer, status, or an advanced openFDA query') but does not add new meaning beyond the schema. 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 explicitly states it searches the FDA Drug Shortages database by various criteria, names the return type (national supply records), and clearly distinguishes itself from local pharmacy inventory or medical advice. The verb 'Search' and resource are specific, making the purpose immediately clear.

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

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

The description provides a clear when-not-to-use directive ('not local pharmacy inventory or medical advice') and notes data sparseness. However, it does not compare this tool to siblings like fda_shortage_changes or fda_drug_approvals, leaving the agent to infer when to choose this tool over alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds that the tool produces aggregated counts rather than raw events, which is useful context. It does not disclose any additional behavioral traits such as pagination, limits, or exact grouping semantics, but the output schema partially covers that.

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

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

The description is two tight sentences with no filler. The central aggregation behavior is front-loaded, and the return summary is stated efficiently. 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?

With two required parameters, 100% schema coverage, rich examples, an output schema, and annotations covering the safety profile, the description is largely sufficient. The main missing element is explicit guidance for distinguishing this tool from overlapping FAERS siblings, but that is more of a usage-guideline gap than a completeness gap for 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 query and count_field with examples. The description names aggregation dimensions like 'reaction type, patient age, or outcome,' which loosely maps to count_field examples, but it does not add meaningful syntax or format details beyond the schema. This matches the baseline of 3.

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

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

The description uses a specific verb and resource: 'Aggregate adverse events by reaction type, patient age, or outcome.' It clearly says what the tool does and what it returns. However, it does not explicitly differentiate itself from closely related siblings like fda_faers_trend or fda_faers_reaction_profile, which also cover reactions and trends.

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

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

The phrase 'Aggregate adverse events' implies this tool should be used when counts or grouped summaries are needed rather than raw event lists. There is no explicit guidance about when to choose this tool over overlapping siblings such as fda_faers_trend or fda_faers_reaction_profile. The usage context is present but only by implication.

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, and the description adds critical behavioral caveats beyond those annotations: the counts are spontaneous reports with duplicates, co-medications, and reporting bias. This is exactly the kind of caveat an agent needs before interpreting the output as an event rate or proof of causation. It also implies the tool aggregates a 'reaction profile' for a drug, which helps 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?

Two sentences, no waste: the first sentence states the function and the output, the second sentence delivers the essential caveat about data interpretation. The caveat is front-loaded in the second sentence, not buried in a wall of text. This is an ideal size for this kind of 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?

The description is complete enough for a read-only aggregate tool with no output schema. It covers purpose, the main parameter, and the key interpretative caveats. The only missing context is the behavior/semantics of 'limit' (does it cap the number of reaction rows? the number of total reports?) and any explicit note about date-range filtering behavior, which the schema partially covers. Overall, strong.

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 50%, so the description has some burden. The description adds meaning for the main 'drug' parameter by calling it a drug identifier, but it doesn't explain the 'limit' parameter. The schema itself provides good guidance for from_date/to_date, including the warning about zero-width windows. The description's caveat about 'co-reported reactions' helps the agent understand what the drug parameter drives, but the limit parameter remains undocumented anywhere.

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 ('Summarize'), a specific resource ('FAERS reactions'), and the output contents ('most frequently co-reported reactions plus serious/non-serious report counts'). It clearly distinguishes itself from the sibling fda_faers_signal_summary and fda_faers_trend by focusing on a per-drug reaction profile rather than a signal or trend.

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 doesn't explicitly name an alternative tool, but the explicit caveat about spontaneous reports, duplicates, co-medications, and reporting bias effectively tells the agent when NOT to use this tool: when the question asks about causation, event rates, or validated safety signals. It also implicitly frames the tool as suitable for exploratory per-drug reaction profiling. Slight gap: it doesn't name a sibling for signal-focused queries.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses several important behaviors: whole-term matching only, natural word order resolution and disclosure, unresolved terms reported as unresolved rather than zero, and the screening-statistic nature of ROR/PRR. This adds substantial context beyond the structured fields.

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

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

The description is concise (three sentences) and front-loaded: it starts with the core calculation, then adds matching nuance, then statistical caveats. Every sentence earns its place 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?

For a tool without an output schema, the description covers the purpose, matching behavior, and interpretation boundaries well. It could explicitly state the return format (e.g., a table with ROR/PRR values), but the description is largely complete for an analysis tool with robust annotations.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds meaningful detail by explaining the neuropathy example for whole-term matching and the unresolved-not-zero behavior, which enriches the reaction parameter semantics beyond the schema text.

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

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

The description opens with a specific verb and resource: 'Calculate report-level FAERS disproportionality routing metrics for one drug/reaction pair using a 2×2 reporting table.' This clearly distinguishes the tool from sibling FDA tools like fda_faers_reaction_profile by emphasizing a single pair and the 2×2 table methodology.

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

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

The description provides clear context for when to use this tool: it is for a single drug/reaction pair and requires exact MedDRA term matching, with explicit notes on how broad words like 'neuropathy' are handled. It also clarifies statistical limitations (not incidence/causality/safety conclusion), which helps rule out inappropriate use, though it does not name specific alternative tools.

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

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

Beyond the readOnly/no-destructive annotations, the description discloses specific behavioral subtleties: exact MedDRA preferred term matching, natural multi-word phrase resolution, unresolved terms reported as unresolved rather than zero, and the caveat that trends reflect reporting activity, publicity, utilization, duplicates, and database updates. This is rich, non-obvious context that significantly aids the agent.

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

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

The description is three sentences, front-loaded with the core purpose, and every subsequent clause adds necessary nuance about reaction matching or interpretation. It is appropriately sized for the tool's complexity without any wasted words.

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

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

The description covers the tool's purpose, reaction behavior, and interpretation caveats thoroughly. Since there is no output schema, it does not fully explain the return structure, but 'aggregate into calendar months' conveys the expected form. It is adequate for a read-only aggregate tool with strong annotations.

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

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

With 0% schema description coverage, the description must compensate. It identifies drug, optional reaction, and a bounded date window (implying from_date/to_date), and thoroughly explains reaction matching semantics. However, it omits details about drug matching (e.g., brand name vs generic) and date format, leaving required parameters only partially clarified.

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 'Aggregate daily FAERS report counts into calendar months for a drug and optional reaction over a bounded date window,' clearly specifying verb, resource, and scope. It distinguishes itself from sibling tools like fda_event_counts or fda_faers_reaction_profile by emphasizing the monthly aggregation and optional reaction filter.

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

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

It gives clear context: use for monthly trends, with an optional reaction, and cautions that trends reflect reporting activity, not incidence or clinical risk. However, it does not explicitly name alternatives or state situations where this tool should not be used, so it stops short of full exclusionary guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the data source and queryable fields but no additional behavioral traits like pagination behavior or response limits. With annotations handling the burden, a mid score is appropriate; there is no contradiction.

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

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

Two sentences, no filler. The core action, resource, content fields, and sibling differentiation are packed into a compact, front-loaded structure. Every clause earns its place.

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

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

For a simple read-only search tool with three optional parameters and no output schema, the description covers the endpoint, result content, usage context, and sibling distinction. The only minor gap is that it doesn't describe default behavior when query is omitted, but the schema already states that. This is complete enough for an agent to call 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%, with each parameter (skip, limit, query) already documented including examples. The tool description adds context about what can be searched but doesn't add parameter-level semantics beyond the schema. Baseline 3 applies since the schema carries the load.

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

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

The description uses a specific verb ('Search'), identifies the resource ('FDA FOOD recall / enforcement reports (openFDA /food/enforcement)'), and lists the covered content fields (product recalls, reasons, classification, recalling firm, distribution, status). It explicitly differentiates from the sibling fda_drug_recalls, making the tool's scope 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?

It explicitly states when to use the tool ('Use for food-safety / recall-history questions') and names the alternative ('distinct from fda_drug_recalls which covers drugs'), giving the agent a clear decision rule. This is direct, actionable guidance rather than implied 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 annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds substantive behavior beyond annotations: results are 'sorted newest-first', it 'Returns original NDA/BLA approvals', and it notes 'generics excluded by default'. This clarifies the operational scope and default filtering behavior, which is valuable for correct invocation.

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 cover purpose, usage context, return content, ordering, default behavior, and exclusions — every sentence earns its place. The main purpose is front-loaded and query examples are grouped into one sentence, making it efficient and scannable.

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

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

Given the tool's moderate complexity, four optional schema-documented parameters, rich annotations, and no output schema, the description is complete. It states what is returned, how results are ordered, the default filtering, and the boundary versus sibling tools. An agent has everything needed to decide when and how 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%, so the schema documents all four parameters in detail. The description adds context around the include_generics default and result ordering, but does not need to repeat parameter syntax. This matches the baseline 3 for high schema coverage where the description provides only marginal parameter-level value.

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

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

The description states a specific resource: 'Most recent novel drug approvals — the newest drugs approved by the FDA.' It names the concrete outputs (approval date, brand name, active ingredients, sponsor, application number) and explicitly distinguishes itself from siblings: 'Not for label text (fda_drug_labels) or searching a specific known drug (fda_drug_approvals).' An agent can tell exactly what this tool is for.

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 contexts with natural-language examples: 'Use for "what is the most recent novel drug the FDA approved", "latest FDA drug approvals", "recently approved new drugs or biologics this month/year".' It also states exclusions and names the alternative tools by name, leaving no ambiguity about when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful context by naming the combined data sources and warning that the output is not a validated safety assessment, which goes beyond the annotations and helps manage 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 composed of two concise sentences: the first states the action and purpose, the second adds essential caveats. There is no redundant wording or unnecessary detail.

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 does not cover parameter details or output format. It provides a strong high-level purpose and limitations, but agents need more information about date ranges and limits to use the tool effectively, especially given the parameter count of 5.

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

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

Schema description coverage is 0%, and the description does not explain any of the five parameters. While 'drug' is implied, to_date, from_date, recall_limit, and reaction_limit are left undefined, leaving the agent without semantic guidance for required inputs.

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

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

The description clearly states the tool's function: combining a drug's FAERS reporting profile, label warning fields, and FDA recall records for review routing. This distinguishes it from sibling tools like fda_faers_reaction_profile, fda_drug_labels, and fda_drug_recalls, which focus on individual data sources.

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 identifies the intended context ('for review routing') and explicitly lists what it is not for (validated safety comparison, causal assessment, etc.), providing clear when-not guidance. It does not name alternative tools for those cases, so it falls short of a 5.

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

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

With readOnly/idempotent annotations already covering safety, the description adds valuable behavioral context: newest-first ordering, look-back windowing, and the data-quality caveat that most rows are 'Reverified' noise. It also tells the agent to pass update_type to filter to meaningful changes, setting correct expectations before invocation.

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

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

Three sentences front-load the core order/window behavior, then provide the use case and the key filtering insight. There is no filler and no repetition of structured schema content.

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

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

Given strong annotations and full schema coverage, the description supplies the remaining operational essentials: sort order, look-back behavior, the Reverified-noise caveat, and the availability limitation. Pagination is already handled by skip/limit in the schema, so 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?

The schema already documents all five parameters at 100% coverage, so the baseline is 3. The description reinforces using update_type to exclude 'Reverified' rows, but this largely mirrors the parameter's existing schema description rather than adding new semantic detail.

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

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

The description opens with a concrete operation: FDA drug-shortage records ordered by update_date, newest first, and restricted to a look-back window. The phrase 'Use for recently updated, discontinued, or resolved national shortages' positions it as a change-driven feed, distinct from a current-shortage status tool like fda_drug_shortages.

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 states an explicit when-to-use scenario ('Use for recently updated, discontinued, or resolved national shortages') and cautions that results do not imply pharmacy/hospital availability, preventing misuse. It does not explicitly name an alternative tool or state when not to use it, so it falls just 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?

Beyond the readOnly/idempotent annotations, the description discloses data coverage (3,680 letters from 2021 onward), the older-archive fallback to 2010, that older records lack a document link, that every row reports its source, and that no caller credential is needed. This is substantial behavioral context that annotations alone do not 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 dense and front-loaded with the core purpose, and every sentence adds useful operational detail. It is somewhat long for a three-parameter tool, but the added coverage and fallback details are not 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?

Although there is no output schema, the description enumerates the fields returned for both data sources, explains the fallback behavior, notes credential requirements, and clarifies match semantics. An agent has enough information to invoke the tool correctly and interpret its results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by explaining how 'search' behaves under the default recipient mode versus fulltext mode, and that matched_field lets callers distinguish 'issued to' from 'mentions'. This goes beyond the schema's field descriptions.

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

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

The description opens with 'Search FDA WARNING LETTERS', naming a specific verb and resource, and then clarifies the scope with official enforcement letters for violations such as CGMP and unapproved claims. It gives concrete example questions that an agent would use to invoke it, making the 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 gives clear guidance on when to use the default 'recipient' match versus match:'fulltext', and explains the fallback to older letters when no recent records exist. It does not explicitly compare against sibling tools like fda_complete_response_letters, so it stops short of full alternatives guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety and write profile are covered. The description aligns with those hints but adds little behavioral context beyond the use cases; it does not, for example, state whether deleting a missing key is an error or what the response looks like. With annotations carrying the main burden, a 3 is appropriate and there is no contradiction.

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

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

Two sentences with no filler: the core action and key-based scoping come first, followed directly by usage guidance and sibling pairing. 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 simple deletion tool with a fully documented schema, explicit destructive/idempotent annotations, and no output schema obligations, the description covers what an agent needs: what it deletes, when to use it, and how it relates to remember and recall. 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%, and the schema already explains that key, k, name, and label are aliases for the memory key. The description adds no parameter-level details, but since the schema fully documents the single meaningful parameter, it does not need to; baseline 3 is correct.

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 pair: 'Delete a previously stored memory by key.' It clearly distinguishes the tool from its siblings remember and recall by naming them and positioning forget as the deletion counterpart, so an agent can select it correctly without opening the schema.

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

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

The description gives explicit triggering conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names the complementary tools remember and recall, routing the agent to its siblings and making the when-to-use decision unambiguous.

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

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

Annotations already declare readOnlyHint=true, 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?

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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered and the bar is lower. The description adds genuine value by disclosing the dual behavior (retrieve vs. list-all-keys when omitting the argument) and the scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID). No contradiction with annotations.

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

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

Three sentences with zero waste: core action first, then usage context with examples, then scoping and sibling pairing. Every sentence earns its place, and the key behavioral distinction (omit key to list all) 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 low-complexity read/list tool with annotations carrying the safety profile and a schema fully documenting the parameters, nothing an agent needs to call it correctly is missing. The dual behavior, scoping, and sibling relationship are all covered despite the absence of an output schema.

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

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

Schema description coverage is 100%, so the schema fully documents all four parameters (which are all aliases for the same key). The description's note about omitting the key to list all keys is mirrored in the schema, so it adds little beyond what structured data already provides. Baseline 3 is appropriate since the schema does the heavy lifting.

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 ('Retrieve a value previously saved via remember, or list all saved keys') with concrete use examples (target ticker, address, research notes). It explicitly differentiates from siblings by naming remember (save) and forget (delete), so an agent can distinguish recall without inspecting other 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 clear context on when to use the tool ('look up context the agent stored earlier... without re-deriving it from scratch') and routes to alternatives ('Pair with remember to save, forget to delete'). It lacks an explicit when-not statement, but the scoping and sibling pairing make the intended usage unambiguous.

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

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

Annotations already 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, so the description adds useful extra context: memory is scoped by identifier, authenticated users get persistence, and anonymous sessions retain memory for 24 hours. 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 compact, front-loaded with the core purpose, and every sentence adds value: usage trigger, storage model, persistence behavior, and related tools. No filler.

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

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

Given the simple write-tool nature, the absence of an output schema is not a serious gap. The description covers what to store, when to store it, persistence limits, and sibling operations. A marginally stronger version would state return behavior or overwrite semantics.

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 key/value aliases and examples. The description only restates the key-value concept without adding deeper semantics, so it meets but does not exceed the baseline 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 opens with a specific verb and resource: 'Save data the agent will need to reuse later.' It clearly differentiates itself from sibling tools by naming recall (retrieve) and forget (delete), so an agent can tell which operation to invoke.

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

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

It gives an explicit trigger condition: 'Use when you discover something worth carrying forward...' and lists concrete examples. It does not state when not to use it, but the guidance is clear enough for most cases.

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

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

Annotations 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.