Openfda

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds valuable context: no cost for default model, requires BYO key for Anthropic, and details the per-model response structure (score, confidence, signals, raw_response) plus a combined view. This goes well 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 three sentences, front-loaded with the main action, and contains no wasted words. Every sentence adds value: purpose, model options, use cases.

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

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

Despite no output schema, the description explains the return format (per-model details + combined view) and scoring range (0-100). With full schema coverage and clear behavioral transparency, the description is complete for an agent to use correctly.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds context for the default model and the use of `_apiKey`, but does not significantly enhance understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about a business or topic and scoring visibility (0-100) per model. It uses specific verbs ('probe', 'score') and distinguishes itself from siblings like 'entity_profile' and 'scan_competitor_ai_presence' by focusing on AI visibility scoring.

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

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

Explicit use cases are provided: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains when to use the default model vs. requiring an API key for Anthropic. However, it does not explicitly state when not to use this tool or provide alternatives, though the context is clear.

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

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

Annotations already carry the read-only/idempotent/open-world safety profile, so the bar is lower. The description adds genuinely useful behavioral context beyond that: it auto-fills arguments, dispatches to the right underlying tool, and returns stable pipeworx:// citation URIs. It doesn't disclose failure modes for unanswerable queries, but for a read-only router the disclosed dispatch-and-cite 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?

Well front-loaded — 'PREFER OVER WEB SEARCH' leads immediately — but bloated at roughly 200 words. 'START HERE for most questions' partially repeats the opening directive, deep_research is recommended twice with different rationales, and the trailing references ('free account', '*-news-feeds packs') are cryptic. Most sentences earn their place, but several say the same thing with different phrasing.

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

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

For a tool with one required parameter, rich annotations, and a complex internal surface (5,767 tools), the description is essentially complete: input form, output form (structured answer + citation URIs), when to use, when not to, and named alternatives. Minor gaps are the lack of unanswerable-query behavior and only partial explanation of the beta/grounded siblings.

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 question parameter is already documented with alias support, so the baseline is 3. The description adds meaning by showing what a good question looks like — six concrete examples ('current US unemployment rate', 'Apple's latest 10-K', 'active clinical trials for GLP-1') — and by disclosing that the tool 'fills arguments,' telling the agent only the natural-language question needs to be supplied.

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: routes a natural-language question to one of 5,767 tools across 1,506 verified sources and returns a structured answer with stable pipeworx:// citation URIs. The scope (authoritative current/historical data with citations) clearly separates it from research-heavy or domain-specific siblings like deep_research and the fda_* family.

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 'PREFER OVER WEB SEARCH,' enumerates trigger phrases ('what is', 'look up', 'find', 'get the latest'), and names alternatives with conditions: deep_research for hallucination-resistant single answers, ask_pipeworx_grounded for reliability notes, and a note that ask_pipeworx already handles breaking news. Deducting because deep_research is recommended for two seemingly opposed cases — single verbatim answers AND multi-part fan-out questions — which muddies the routing decision.

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

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

Annotations already provide readOnly, openWorld, idempotent, and non-destructive hints, so the descritption adds value by disclosing the beta status, the absence of an active candidate, and the fact that it currently matches ask_pipeworx exactly. It also clarifies that it is a full working router with no degraded fallback, which is useful behavioral context. No trait contradicts 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 beta identity and then provides the current state, usage guidance, and non-fallbak assurance in a compact three-sentence structure. The exact tool count and retirement date add specificity without being excessive. Some redundancy exists between 'identical universal router' and 'currently matches ask_pipeworx exactly,' but it does not harm clarity.

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 stable annotations and full schema, the description covers the essential context: what beta means, the current equivalence to ask_pipeworx, and the fact that it is a complete working router. It does not describe the output payload, but it points to the identical response shape of ask_pipeworx, which is acceptable when the sibling tool is available. The description is complete enough for an agent to decide when and how to invoke it.

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

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

Schema description coverage is 100%, and the schema already documents all six parameters including the aliases and the required question field. The description does not add parameter-level information beyond noting that the tool accepts the same arguments as ask_pipeworx. With full schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly identifies this as a beta variant of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It distinguishes the tool from the stable ask_pipeworx by framing it as the experimental edge with candidate routing improvements. However, it relies on prior knowledge of ask_pipeworx itself and does not directly state the user-facing function of the router.

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

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

The description explicitly says to use it exactly like ask_pipeworx when you want the newest routing, giving a clear use condition. It also explains that results are compared against the stable router to decide merges. It does not explicitly state when not to use it or mention alternatives like ask_pipeworx_grounded, but the beta-vs-stable distinction is sufficient.

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

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

Annotations already signal readOnlyHint, openWorldHint, and idempotentHint, so the description goes beyond that by detailing refusal reasons, evidence extraction, the returned payload, and the extra LLM call cost. It also explains the failure semantics with refusal_reason values, giving agents a precise behavioral contract.

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 adds operational value: purpose, mechanics, return shape, refusal modes, appropriate use cases, and cost tradeoff. It is front-loaded with the core distinction and uses structured enumeration rather than waffle.

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 is high-stakes and has no output schema, the description compensates fully by listing the success return shape and every refusal reason. It also captures the when/why, the alternative, and the cost implication, so an agent has everything needed to decide and call safely.

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 documents the question parameter and its aliases clearly. The description does not add parameter-level detail beyond that, so the baseline 3 is appropriate.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads' and explains exactly what the tool does: routes through the same tool selection as ask_pipeworx, fetches data, then extracts an answer only from the tool result. It clearly distinguishes this tool from ask_pipeworx and other siblings by emphasizing evidence-based answering and refusal behavior.

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

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

The description explicitly states when to use this tool: whenever an answer will be quoted, cited, or acted on and facts must not be invented, with examples such as financial verdicts and legal claims. It also gives a clear alternative and preference rule: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call cost.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint false) already indicate safe read behavior. Description adds extensive behavioral details: fan-out logic, classifiers, response shapes, resolver contract (confidence levels, alternatives), parent event extraction, news fallback handling, safety checks (low confidence, closed markets), spread warnings, and cancellation rule parsing. 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?

Description is quite lengthy (multiple paragraphs) and covers many details. While all information is relevant, it could be more concise. Front-loads purpose well but overall verbosity reduces conciseness score.

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 and high complexity, the description thoroughly covers response shapes, resolver contract, parent event extraction, news fields, safety mechanisms, and cancellation rules. Provides complete context for an agent to understand all behavior and outcomes.

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 has 100% coverage with descriptions for each parameter. Description adds value by elaborating on market input formats (slug, URL, question text) and provides examples for depth and include_raw, though schema already covers basics. Fan-out examples give context but are not strictly parameter semantics.

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

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

Clearly states it researches a Polymarket bet by pulling Pipeworx data. Gives multiple input formats (slug, URL, question text) and explicit use cases ('should I bet on X', 'what does the data say about Y'). Very specific verb+resource with examples.

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

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

Provides explicit use cases for when to use the tool ('Use for...'). Does not explicitly state when not to use it or compare to sibling tools like polymarket_edges, but the context signals show many siblings, and no exclusions are given. Still, clear usage context.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), sorting by primary metric, and return of citation URIs. No contradiction.

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

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

The description is information-dense but efficient. Every sentence adds value, though it is slightly long. It front-loads the core purpose and includes examples and instructions.

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 entity types, multiple data fields), the description covers all essential aspects: input format, data retrieved, sorting, and return format (paired data + citation URIs). No output schema, but description compensates adequately.

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

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

Schema coverage is 100% with descriptions for both parameters. The description enhances understanding by specifying allowed values (tickers/CIKs for company, drug names for drug) and explains sorting behavior. Examples are 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 tool performs side-by-side comparisons of 2-5 companies or drugs in a single parallel call, with specific example queries like 'compare X and Y' and 'rank these companies'. It distinguishes itself from sequential lookups.

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

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

It explicitly instructs to prefer this tool over sequential single-pack lookups when comparing entities. It provides context on when to use (comparison queries) and implies not for single entity lookup, with sibling entity_profile available.

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 the execution model (facets routed in parallel to 5,767 tools), output format (verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[]), the 'never invented' guarantee, citation fetchability conditions, semantic excerpting of long records, and expected latency of 15-60s (up to ~90s). This is extensive behavioral context not carried by 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 purpose and the crucial account/alternative note, and it is logically organized. However, it is very long, contains corrupted text (e.g., 'not head-truncuncated', the garbled 'depth:"standard"' paragraph with '...'), and repeats depth details already present in the input schema. It could be tightened without losing 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?

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It covers account requirements, alternatives, scope, return packet structure, citation semantics, gap/contradiction behavior, excerpting policy, and latency. An agent making a go/no-go or invocation decision has everything needed.

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

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

The schema already covers 100% of parameters, including detailed enum descriptions for depth, so the baseline is 3. The description adds value on top: it ties the 'thorough' depth to a paid plan, explains standard/thorough behavior in terms of gap recovery and contradiction scans, provides example questions, and warns about latency per depth. This exceeds the schema but partially duplicates it, so not a 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 uses a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources' and names an explicit output ('findings packet'). It distinguishes itself from siblings by stating 'this is NOT open-web search' and 'For a single lookup use ask_pipeworx instead', so an agent can tell it apart from ask_pipeworx and the many specialized FDA/Polymarket tools without opening their 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?

It gives explicit when-to-use and when-not-to-use guidance: use for 'broad/multi-part questions over structured data', avoid for 'a single lookup' in favor of ask_pipeworx, and use ask_pipeworx if not signed in. It also explains depth choices by noting 'thorough' is paid and 'standard' is the default, making selection criteria concrete.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds details about returning top-N relevant tools with full input schemas and curated examples, ready to call directly. No contradictions.

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

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

Description is informative but could be slightly more concise. However, each sentence adds value and it's well-structured with a clear front-load of purpose and usage.

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

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

Given no output schema, the description explains it returns top-N tools with names, descriptions, and full input schemas with examples. Complete enough for a tool discovery 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 has 6 parameters with 100% description coverage, so baseline is 3. The description adds clarification about aliases (q, task, search, description) all mapping to 'query', and limit info. Adds some value beyond schema.

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

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

The description clearly states the tool finds tools by describing data or task, lists many example domains, and distinguishes from sibling tools (which are specific data tools). It's a discovery tool, not a data retrieval 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?

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for ...' and 'Call this FIRST when you have many tools available and want to see the option set'. Clear guidance on when to use.

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

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

Annotations already signal readOnly/openWorld/idempotent, and the description adds substantial behavioral detail: USPTO PatentsView API soft-fails after sunset, an empty fda_products section is expected for companies without biologics, unresolved private companies return resolved:false with a notes line, and sources_used/sources_failed distinguish real 'no data' from bugs. 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 long, but the tool is complex and almost every clause earns its place by documenting a source, output field, or failure mode. It front-loads the trigger examples and the ALWAYS PREFER guidance, then uses semicolon-separated lists to keep the dense content navigable.

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 and high tool complexity, the description carries the full burden and meets it: it lists every return section, the input shapes, resolution behavior, expected empty results, soft-failure handling, and source-tracking fields. An agent has enough context to select, parameterize, and interpret the tool's response correctly.

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

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

Schema coverage is 100% and both parameters are already documented with examples, so the baseline is 3. The description adds useful nuance: zero-padded CIK expectations, SEC EDGAR name resolution, interchangeable type values, and the private-company resolved:false behavior, which clarifies parameter semantics beyond the schema.

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

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

The description states a specific verb and resource: 'full cross-source profile of a US public company in ONE parallel call,' and enumerates distinct data sources and return sections. The example queries ('Tell me about X', 'brief me on Tesla', 'company profile for Microsoft') make the intended use immediately recognizable and distinguishable from single-purpose siblings like fda_application_history or resolve_entity.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' which gives a clear when-to-use rule versus a whole category of alternatives. It also explains how to handle private companies and empty result sections, so the agent knows what outcomes to expect.

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?

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds specific behavioral details: ordering by update_date, newest-first, and restriction to a look-back window. The caveat about pharmacy availability also provides helpful transparency 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 that are concise and front-loaded: the first sentence states the core functionality, the second provides usage guidance and a caveat. Every word earns its place.

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

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

For a read-only, filtered-list tool with good annotations, the description covers purpose, ordering, filtering, and a crucial limitation. Lack of output schema is somewhat mitigated by the simple nature of the tool. A brief note on return fields would make it fully complete, but it's adequate.

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

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

Input schema has 100% coverage with descriptions for days, limit, and status. The description mentions 'look-back window' and 'optional status' but adds little beyond the schema. With full schema coverage, a score of 3 is appropriate as the description 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?

Description clearly states it returns FDA drug-shortage records ordered by update_date, newest first, restricted to a look-back window. It specifies the use case (recently updated, discontinued, or resolved national shortages) and distinguishes from sibling tools like fda_drug_shortages which likely lack date ordering.

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

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

Explicitly states 'Use for recently updated, discontinued, or resolved national shortages' and includes a caveat about availability. However, it does not directly mention when not to use this tool or explicitly name alternatives (e.g., fda_drug_shortages for unfiltered lists), which would further clarify selection.

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

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

Even with readOnlyHint/idempotentHint annotations already covering the safety profile, the description adds substantial behavioral detail: default recipient matching, fulltext mode semantics, the matched_field output disambiguation, coverage of ~3,660 letters, and the return fields. It also notes the data is keyless and live from fda.gov, which is useful context 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: purpose and example questions come first, then matching behavior, then scope, return contents, and data source. Every sentence adds information, and there is no filler or repetition of schema content beyond what is useful for orientation.

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

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

With no output schema, the description compensates by listing return fields: recipient company, dates, issuing office, subject, link, and matched_field. It also specifies search semantics, default behavior, coverage size, freshness, and authentication requirement (none), making it sufficiently complete 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 description coverage is 100%, and the input schema already thoroughly explains 'search', 'match', and 'limit', including defaults, enums, and the recipient-vs-fulltext distinction. The description mostly reinforces these semantics rather than adding meaningfully new parameter-level detail, so the baseline score of 3 is appropriate.

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

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

The description opens with 'Search FDA WARNING LETTERS — official enforcement letters FDA sends firms for violations', naming a specific verb, resource, and defining scope. It gives concrete example questions ('has <company> received an FDA warning letter') and distinguishes the tool from siblings like approvals and recalls by focusing on warning letters and recipient enforcement history.

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 usage context through example queries and explicitly explains when to use the default 'recipient' match versus 'fulltext' search, including that fulltext finds letters that merely mention a firm. It does not name alternatives among sibling tools or state when not to use this tool, 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the description adds minimal behavioral insight beyond 'delete'. No contradiction, but no added value.

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

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

Two efficient sentences covering purpose, usage context, and sibling references with zero fluff.

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

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

Sufficient for a simple destructive but idempotent tool with good annotations. Could mention idempotent behavior, but not critical.

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

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

Schema coverage is 100% with a clear description of the 'key' parameter. The tool description does not add extra semantic meaning beyond what the schema provides.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb and resource. It also references sibling tools 'remember and recall', distinguishing itself as the deletion counterpart.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. It also advises pairing with 'remember and recall', providing clear alternatives.

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

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

The description goes beyond annotations by detailing the process: fetches the page, extracts title/description/key links, and emits standard markdown format. It also states the output is a single text blob ready for placement, providing rich 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 concise with three front-loaded sentences covering purpose, output format, and use cases. No wasted words; every sentence adds value.

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

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

Given the rich annotations and schema, the description provides sufficient context: what the tool does, how it works, output format, and use cases. Minor omissions like error handling or invalid URL handling do not detract significantly from completeness.

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

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

Schema description coverage is 100% for both parameters (url and max_links). The description does not add extra semantics beyond what the schema already provides, so 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 tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate', the resource 'llms.txt file', and the context 'for any URL'. It distinguishes itself from sibling tools which are mostly FDA-specific or unrelated.

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 lists use cases: getting a client's site indexed, drafting for own project, auditing competitor. It provides clear context for when to use the tool, though does not explicitly state when not to use it or alternatives, which is acceptable given no similar sibling 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?

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds that it lists active subscriptions by default and returns specific fields, which is useful context beyond annotations.

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

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

The description is two efficient sentences: first states action and output, second provides usage guidance. No redundant information.

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

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

For a simple listing tool with no output schema, the description sufficiently covers return fields and typical usage. It could mention pagination or limits, but the tool appears unbounded.

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

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

Schema coverage is 100%; the parameter include_inactive is described in the schema. The description implicitly relates to this by mentioning 'active subscriptions', adding marginal value.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields (id, type, etc.). It distinguishes from siblings like subscribe and unsubscribe by mentioning review and id 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 explicitly advises when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This guides the agent on appropriate invocation contexts.

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

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

Beyond the annotations (all false), the description discloses several valuable behaviors: filing without an account returns a claim_token, the token can be passed back later to read resolution status, the tool is rate-limited to 5 per identifier per day, and it is free and doesn't count against quota. These are non-obvious behaviors the annotations do not 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 longer than average, but every sentence earns its place: it defines the tool, provides use/non-use cases, gives content guidance, explains the token flow, and mentions limits. It is front-loaded with the core purpose and structured logically, with no redundant 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 tool has no output schema, the description covers the return token behavior and later status reading. It also covers rate limits, quota impact, and the team's response cadence. For a feedback tool with multiple edge cases and a two-phase claim-token flow, this is fully complete.

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

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

Schema coverage is 100% and each parameter already has a description, so the baseline is 3. The description adds semantic guidance by telling the user to describe issues in terms of Pipeworx tools/packs, not to paste end-user prompts, and clarifies the claim_token round-trip workflow. This is a meaningful value-add over the schema.

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

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

The description names a specific verb+resource ('Tell the Pipeworx team') and enumerates the exact kinds of feedback (bug, feature/data_gap, praise). It clearly distinguishes from sibling tools by scoping to 'tools served by this Pipeworx connection' and even warns against filing for other MCP servers.

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

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

It gives explicit when-to-use triggers: wrong/stale data, missing tools or data, praise. It also gives an explicit when-not-to-use with a redirect: if the tool came from a different MCP server, file with that server. This is exactly the kind of decision guidance agents need.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive. The description adds: self-aggregating signal, derived from CF analytics-engine, no PII, data format (pack, tool, count), and caching behavior (5min-1h). This provides rich 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?

Five well-structured sentences with bullet-like use cases. Front-loaded core functionality. Every sentence adds value with no redundancy or fluff.

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

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

For a simple read tool with one optional parameter, the description covers return format, data source, caching, and use cases. No output schema exists, but that's acceptable given the simplicity. The information is sufficient for an agent to decide 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?

Schema coverage is 100% with good description of the window enum. The description adds practical guidance: shorter windows for hotness, longer for steady-state, and notes default (24h). This adds value beyond the schema.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a window, with explicit use cases (discovering data sources, confirming popular tool, aligning use case). It distinguishes from siblings by being the only trending/aggregation tool in the list.

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

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

Three explicit use cases are provided, and window selection guidance is given (shorter for current hotness, longer for steady-state). However, it does not explicitly state when NOT to use this tool or mention alternatives, though the context implies it's for discovery rather than direct 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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive; description adds rich detail on internal logic (monotonicity, partition checks, semantic anchor, partition filter, fill check), response structure, and caution about unrealizable edges. 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?

Well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK), front-loaded with main purpose. While lengthy, each sentence adds distinct value; minor verbosity but appropriate for complexity.

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

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

No output schema, but description fully explains response fields (opportunities[], partition_check, fill_check details). Covers edge cases (placeholders, low similarity, unrealizable edge) and gives sufficient context for a complex arbitrage 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 has 100% coverage with descriptions; description adds examples ('fed-decision-may-2026', 'Fed rate decision') and explains each mode's behavior in depth (walking child markets, computing partition_check, searching related events), far exceeding schema.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes modes (no args, event, topic) and verbs like 'Find' and 'scan', and differs from siblings like polymarket_edges or polymarket_fill_risk.

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

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

Explicitly tells when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. Recommends event mode and explains cross-event mode catches missed patterns. Also references polymarket_fill_risk for custom sizing, providing 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?

Annotations already indicate readOnly, idempotent, and non-destructive. The description significantly adds value beyond annotations by detailing caching ('Cached 1h at the KV level'), model families, response segments, diagnostics, and edge metrics. 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 front-loaded with purpose and is structured into clear sections. While detailed, every sentence adds value; it could be slightly more concise but remains well-organized.

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 9 parameters, no output schema, and rich annotations, the description is exceptionally complete. It explains the response structure (by_segment, diagnostics), caching, edge metrics, Fed note, and tradeable-edge filters, covering all necessary context for agent 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% with detailed parameter descriptions. The tool description does not add additional meaning for individual parameters beyond what is already in the schema. 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 tool's purpose: 'Scan top Polymarkets...return opportunities where Pipeworx data disagrees with market price.' It targets 'what should I bet on today' use case, distinguishing it implicitly from sibling tools like polymarket_arbitrage or polymarket_edge_tracker via unique functionality.

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

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

The description provides context for when to use (discovering opportunities without paging) and explains tradeable-edge knobs (min_liquidity, max_spread_pp) to filter unrealistic opportunities. However, it does not explicitly mention when NOT to use or offer direct alternatives among siblings.

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

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

The description adds significant behavioral context beyond the annotations (readOnlyHint, etc.): it explains data sources (daily snapshots), TTL (60-day snapshot TTL), when snapshots are missing (no cache-miss scan), and that decay numbers are from daily closes, not intraday. This fully informs the agent of underlying behaviors and limitations.

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

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

The description is fairly long but every sentence adds value. It front-loads the main purpose and then details output format and limits. Could be slightly more structured (e.g., bullet points for output fields), but remains effective and concise for the amount of information conveyed.

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

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

With no output schema, the description fully explains the return format (tracked[], expired[], snapshot_dates[]) and key fields. It also covers limitations like TTL, start date, and data frequency. This makes the tool fully self-contained for agent 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 input schema already documents both parameters with descriptions and default values. The description adds additional clarity by restating defaults and clarifying the max for days, and listing valid window options. This provides a slight improvement over the schema alone.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots. It explicitly answers a specific trading question about edge age and trend, and distinguishes itself from the related sibling 'polymarket_edges' by focusing on historical context rather than current edges.

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

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

The description gives context on when to use the tool (e.g., to differentiate a new wide edge from a stale one) and explains the arguments in the description. While it does not explicitly state when not to use it or list alternatives, the context is sufficient for most agents to decide appropriately.

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

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

Annotations already provide read-only and idempotent hints. The description adds valuable behavioral context: it walks the order-book ladder, returns specific fields (top_of_book, vwap_fill_price, etc.), and mentions forced_directional_risk. No contradiction.

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

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

The description is a single dense paragraph with rich information but could be structurally improved with bullet points or clearer separation of modes. It is front-loaded with purpose.

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

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

Given complexity (two modes, many return fields) and no output schema, the description adequately covers return values (top_of_book, vwap_fill_price, slippage_pp, etc.) and risks. Sufficient for an agent to understand the tool's full behavior.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning beyond schema: explains defaults, side auto-behavior for basket, and size_usd interpretation differences between modes. Clarifies value clamp.

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

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

The description clearly states the tool performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and specifies two modes (single-market and basket), effectively distinguishing it from siblings like polymarket_arbitrage.

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

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

Explicitly tells when to use this tool ('before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500') and explains risks (theoretical overrun not capturable, partial fills cause unhedged positions).

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 substantial behavioral detail: matching is keyword/word-overlap based, compatibility codes can be non-empty even when pairs are returned, unknown legs are never paired, fees are not modeled, and spreads are gross rather than net tradeable edge. 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 and dense, but it is sectioned (modes, response, safety fields, codes, fees, counters) and nearly every sentence adds a caveat an agent needs before trusting a spread. It earns its length, though it is slightly over-stuffed and could be tightened.

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

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

There is no output schema, so the description carries the full burden of explaining the response shape. It covers leg-by-leg prices, top_spreads_pp, compatibility warnings and codes, per-entry flags, temporal alignment semantics, fee disclosure, and skipped-comparison counters. For a tool this complex, the description is exceptionally complete.

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

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

Schema coverage is 100% and each parameter already has a description, so the baseline is 3. The description adds extra semantic value by explaining the override relationship between topic and explicit ticker/slug, and by noting that both modes run the identical token-overlap matcher.

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 opening sentence states the exact deliverable: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It names both venues and the specific output measure, which clearly distinguishes it from the Polymarket-only sibling tools without needing to name them.

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

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

The description clearly explains when to use each of the two modes—pre-mapped topic shortcuts versus explicit kalshi_event_ticker + polymarket_event_slug—and warns that pre-mapped topics are not inherently tradeable. It gives strong usage context, though it does not explicitly contrast this tool with potential sibling 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=true, destructiveHint=false. Description adds scoping to identifier and behavior when omitting key. No contradictions.

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

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

Three sentences cover main function, usage context, and scope. Front-loaded and efficient with no extraneous 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?

Simple tool with one optional param, no output schema, and annotations cover safety. Description explains return behavior, scope, and tool pairing completely.

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 description for key. Description adds: 'omit the key argument' to list all keys, reinforcing schema behavior.

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

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

Description clearly states 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' Verb and resource are specific, and it distinguishes from sibling tools 'remember' and 'forget'.

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

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

Explicitly says 'Use to look up context the agent stored earlier' with examples like ticker, address, notes. Indicates alternative to re-deriving and pairs with remember/forget.

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 indicate readOnlyHint, idempotent, and non-destructive. The description adds that setting mark_read:true flags events as read, affecting subsequent calls, and confirms that polling works. This provides useful behavioral context 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 concise, with every sentence adding value. It is front-loaded with the main purpose and efficiently covers features, alternatives, and usage notes in just a few sentences.

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 specifies the return fields (source, citation_uri, raw payload) and covers key behaviors (filtering, mark_read, polling). It also provides an external access point, making it self-contained and complete for a list tool.

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

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

Schema covers all 5 parameters, so baseline is 3. The description adds value by explaining the effect of mark_read (flag events read) and providing an example filter for 'type' ('sec_8k'), enhancing understanding beyond the schema's short descriptions.

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

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

The description clearly states the tool's function: pulling fired events from the subscription feed with specific fields (source, citation_uri, payload). It effectively distinguishes itself from sibling tools like 'list_subscriptions' and others by focusing on recent alert events from a persisted 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?

The description provides usage context (filtering by type and since, using mark_read) and mentions an alternative access method via a direct GET endpoint. However, it does not explicitly state when to prefer this tool over others, though no similarly purposed sibling exists.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds significant detail: fans out to multiple sources (SEC, GDELT/GNews, USPTO), explains fallback logic, and describes the return structure (changes[], total_changes, citation URIs). No contradiction.

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

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

The description is a single, well-organized paragraph that loads the primary purpose and examples first, then details sources, parameters, return values, and finally an alternative tool. Every sentence provides essential information without redundancy.

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

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

Despite having no output schema, the description fully describes the return structure and behavior. It covers all three parameters exhaustively, explains multi-source fan-out and fallbacks, and provides a clear alternative for different use cases. Complete for a read-only query tool.

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

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

Schema coverage is 100%, but the description enhances parameter understanding: specifies that 'since' accepts ISO dates or relative shorthand (e.g., '7d', '30d'), recommends '30d' or '1m' for typical monitoring, and explains the 'type' parameter only supports 'company'. This adds practical guidance beyond the schema.

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

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

The description clearly states the tool provides a change feed for a company over a specified window, with concrete example queries. It explicitly distinguishes from the sibling tool 'entity_profile' by noting that tool is for static profiles regardless of window.

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 this tool vs. alternatives, specifically recommending 'entity_profile' for static profiles. It also clarifies fallback behavior between GDELT and GNews and notes the soft-fail for USPTO, giving clear usage context.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds context about scoping (by agent identifier), persistence (authenticated vs anonymous sessions), and retention duration (24 hours), which go beyond annotations.

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

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

The description is concise with about five sentences, front-loading the purpose and usage, then adding details. Every sentence adds value without redundancy.

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

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

For a simple key-value save tool with no output schema, the description covers all necessary context: purpose, usage, scoping, persistence, and pairing with siblings. No gaps.

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

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

Schema coverage is 100% with clear descriptions for key and value. The description reinforces the purpose but does not add significant new meaning beyond what the schema provides.

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

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

The description clearly states the purpose: 'Save data the agent will need to reuse later.' It provides specific verb-resource combination and mentions sibling tools (recall, forget) 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?

The description explicitly says when to use: 'when you discover something worth carrying forward.' It also provides alternatives by directing to recall and forget for complementary operations.

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 though annotations already mark the tool read-only, idempotent, and non-destructive, the description adds rich behavioral detail: graceful degradation if GLEIF/OpenFIGI is down, explicit `unresolved` handling rather than silent omission, `figi_candidates` on ambiguity, and internal cascading across multiple lookup endpoints. This substantially exceeds what the 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 and front-loaded with purpose and usage, but it is long and at times run-on, mixing many details into one extended passage. There is no filler, yet tighter bullet-style structuring would improve scannability.

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

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

With no output schema, the description compensates well by disclosing identifier sources, unresolved handling, ambiguity behavior, and degradation. It still does not fully define the response envelope or failure format, but the agent has enough 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?

Schema coverage is 100%, but the description adds critical semantic guidance beyond the schema: pass only the issuer name, never the bond's full noun phrase, because trailing security-class words break the FIGI lookup. It also clarifies ticker/CIK/ISIN/name inputs and the ISIN-to-LEI path, which materially improves correct invocation.

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

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

The description opens with concrete natural-language queries and states exactly what the tool does: resolving a spoken/plain name to canonical official identifiers required by other tools. It clearly distinguishes itself from siblings like entity_profile by emphasizing identifier resolution rather than profile 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?

It explicitly says 'Use FIRST whenever you have a name but need an ID' and gives many query patterns that trigger this tool. It does not explicitly list when NOT to use it or name a sibling alternative, so it falls just short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint. The description adds that it probes each entity, ranks by score, and returns a ranked list. It could mention potential time or cost when using Anthropic model, but overall adds relevant process details.

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 efficiently cover purpose, method, use case, and output. Every sentence adds value, no fluff. Front-loaded with key functionality.

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

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

Even without an output schema, the description explains the return format (ranked list with score, confidence, signal density per entity). It covers multi-entity probing, ranking, and extremes. Parameters and usage are well-explained. No gaps.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds meaningful context beyond schema: first entity is treated as subject, models supported, and context disambiguation. This helps the agent use parameters correctly.

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 compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes from sibling ai_visibility_check by emphasizing multi-entity comparison.

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

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

The description provides a concrete use case (competitive AI-marketing audits) and an example question. It implies usage for multiple entities but does not explicitly say when not to use it or mention alternatives for single entities.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds valuable context: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed lists timeouts. No contradictions.

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

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

Description is detailed but front-loaded with purpose and use cases. It includes important caveats without being overly verbose. Could be slightly more concise but still effective.

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, description fully explains the return summary block (is_latest, license, etc.), per-advisory detail, links, and alternative versions. Also covers failure modes and ecosystem limitations, making agent invocation robust.

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 baseline is 3. Description adds minimal extra meaning beyond schema: only mentions that scoped packages are accepted. Does not elaborate on version format or defaults beyond schema.

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

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

The description clearly states it's a composite check for npm packages covering deps.dev and bundlephobia. It uses specific verbs ('scan', 'check') and distinguishes itself from sibling tools which focus on other domains.

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 agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also notes NPM-only in v1 and provides alternative for other ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly').

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable details not in annotations: embedding model (BGE-base-en), window size (500-char overlapping), character limit (200K chars with truncation flag).

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

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

Description is three sentences; first states purpose, second gives usage guidance, third technical details. Efficient but could be slightly tighter. No wasted words.

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

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

No output schema, but description explains return values (passages with offsets and scores). Covers input constraints, usage guidance, pairing with sibling, and technical details (model, window, cap). Complete for a search 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% (all params described in schema). Description adds practical context: text max chars, limit default (5) and range (1-20), query examples. Adds value beyond schema.

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

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

The description clearly states the tool does 'semantic search INSIDE a fetched record,' specifies inputs (text and query), outputs (top-N passages with offsets and scores), and distinguishes it from sibling tools like ask_pipeworx_grounded.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and describes pairing with ask_pipeworx_grounded. Does not explicitly list when not to use, but the context is clear enough.

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

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

Annotations already indicate non-destructive and idempotent behavior. Description adds rich behavioral context: account requirements, type-specific parameters, delivery channels, SMS cap, webhook signing, and auto-disable on failures. 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?

Description is fairly long but well-structured with bullet points and clear separation of types and delivery options. Every sentence adds value; could be slightly shorter but still effective.

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 (3 params with nested objects, multiple enum types, delivery options, no output schema), the description is extremely complete. It explains return value, covers all types, and notes additional requirements.

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 description adds substantial meaning: explains each type's params with examples and clarifies constraints (e.g., sponsor or condition required for clinical_trial).

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

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

Description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. It lists supported types and distinguishes from siblings like 'list_subscriptions' 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?

Provides clear when-to-use guidance and prerequisites (Pipeworx OAuth account, phone verification for SMS). Lacks explicit when-not-to-use but context is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral context: it returns example questions, organizes them by category, and mentions the response includes exact tool+argument shapes. This goes beyond the annotations 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 a single paragraph that front-loads alternative phrasings, then explains output and usage. Every sentence contributes meaningful information, though it could be slightly more compact. Overall well-structured.

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

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

For an onboarding tool with no output schema, the description fully explains what the tool returns (category-bucketed example questions with tool+argument shapes) and when to use it. It covers all necessary context given the simple input 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 schema covers the single optional parameter 'topic' with a description. The description reinforces it and adds practical advice: 'Call with no arguments for the full spread, or pass topic... to focus.' This adds value beyond the schema.

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

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

The description clearly states what the tool does: it returns category-bucketed example questions to help users understand what they can ask Pipeworx. It distinguishes itself from sibling tools like ask_pipeworx or entity_profile by being the first entry point for onboarding.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Provides guidance on when to call with no arguments vs. passing a topic parameter.

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 ownership enforcement (auth) and deactivation behavior, adding context beyond annotations. Consistent with idempotentHint and destructiveHint.

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, efficient and clear without extraneous content.

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

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

Given simple tool with single parameter, rich annotations, and no output schema, the description provides complete context for usage.

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

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

Schema coverage is 100% with clear parameter description ('Subscription id (uuid) returned by subscribe'). Description adds no further parameter-specific information, meeting 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 uses specific verb 'cancel' with resource 'subscription', clearly stating what the tool does. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

States ownership enforcement, guiding who can use it. Explains the deactivation behavior, but does not explicitly list when not to use or alternatives.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses critical behaviors: could_not_verify means the check failed and must not be treated as evidence, unsupported means no source was found, and results include citations and reasoning. It also explains the internal routing logic and that the tool replaces multiple sequential calls.

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 segment earns its place: trigger examples, usage rule, dual-path explanation, verdict list, and critical caveats about error states. It is front-loaded with the core purpose and well-structured, though it could be tightened without losing value.

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

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

Without an output schema, the description fully covers the return contract: verdicts, actual value with citation, reasoning, and the meaning of every verdict, including error details. It also explains the underlying pipeline and edge cases, giving the agent a complete mental model of what the tool does and when results are trustworthy.

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, giving a baseline of 3. The description adds concrete operational guidance: tolerance_pct overrides the tolerance implied by claim wording, is capped at 5 by default, and should be set to 1–2 for hallucination detection. This useful context goes beyond the schema.

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

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

The description clearly states the tool performs natural-language claim verification against authoritative sources, with explicit trigger phrases like 'fact check' and 'verify the claim that…'. It distinguishes a financial fast path from a grounded pipeline, giving the tool a unique, well-scoped purpose among 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?

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' and differentiates when to use the SEC fast path versus the grounded pipeline. It lacks explicit alternatives or exclusion guidance, so it doesn't fully score 5, but the context is strong.

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