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 state readOnly, openWorld, idempotent, and non-destructive. The description adds meaningful behavioral context: it fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, is one fast call, and works on every tier. 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 long but front-loaded and organized: priority directive, then scope, then examples, then escalation paths. The 'START HERE' sentence is slightly redundant with the opening, but every other section earns its place for a default entry-point 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?

With no output schema, the description explicitly covers return value (structured answer with citations). It provides use contexts, examples, sibling comparisons, and tier behavior, making it fully self-contained for an agent to decide when and how to invoke the tool.

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

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

Schema description coverage is 100%: all six parameters are documented as aliases for the natural-language question. The description adds example queries and clarifies that any of q, query, prompt, text, or input are accepted, but this largely restates 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 is explicit: it is a general-purpose question-answering tool that routes to one of 5,529 tools and returns structured answers with citation URIs. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the fast default entry point.

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

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

Gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and lists concrete trigger phrases and example queries. It also names alternatives and when to step up: ask_pipeworx_grounded for verbatim evidence and deep_research for broad/multi-part questions.

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

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

Annotations already mark readOnly/idempotent/non-destructive; description adds valuable context about live candidate testing, current exact equivalence to the stable router, results comparison, and the fact that it is fully functional. 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?

The description is three sentences, front-loaded with the key identity, and each sentence adds necessary caveats about beta status and current behavior. Slightly long but not wasteful.

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 compensates by stating the response shape matches ask_pipeworx exactly. Simple single-question input with 100% schema coverage, annotations cover safety profile. Missing explicit return-value details but sufficient for a beta router 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 100% of parameters with aliases, and description says 'same arguments' as ask_pipeworx. No additional parameter-level meaning is added beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router with the same 5,529 tools. It distinguishes from the stable ask_pipeworx by noting experimental routing improvements and fallback to nothing, but it does not explicitly contrast with the sibling 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?

It instructs to use exactly like ask_pipeworx when wanting the newest routing, and explains the current state (no active candidate, so behavior matches stable). It provides clear context but does not explicitly list when to avoid using this tool or name exclusions for grounded variants.

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, but the description adds valuable behavioral context: returns a structured result with {answer, evidence, confidence, source, fetched_at} or an explicit refusal with specific reasons. It also discloses the 'using ONLY what the tool result contains' constraint and the extra LLM call overhead. 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 front-loaded with the core purpose, then provides practical usage guidance and return structure. Every sentence adds value—no fluff or repetition. It is moderately long but justified given the tool's complexity.

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

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

Even without an output schema, the description fully explains the return format, including success fields and the refusal_reason enum. It covers the tool's behavior, cost, and differentiation from siblings, making it self-contained for an agent to correctly invoke and interpret results.

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

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

Schema coverage is 100% for all 6 parameters (all aliases for question), and the description already states 'Accepts query, q, prompt, text, input as aliases.' The description does not need to add further parameter-level detail; it matches the schema.

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

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

The description clearly identifies a specific mode: 'Hallucination-resistant answer mode for high-stakes reads' and explains it routes through the same pipeline as ask_pipeworx but 'EXTRACTS the answer using ONLY what the tool result contains.' This distinguishes it from the sibling tool ask_pipeworx while stating the exact verb and resource.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. Also provides the alternative: 'prefer ask_pipeworx for casual lookups' and mentions the extra LLM call cost as a trade-off.

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 (readOnlyHint, openWorldHint, idempotentHint), the description richly discloses behaviors: decomposition into facets, parallel routing, gaps[] that are 'never invented', resolvable citation_uri, contradictions[] for deeper depths, semantic excerpting, expected latency (15-90s), and account tier requirements. It also notes that current-news topics will return mostly empty gaps[]. 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?

Though long, every sentence earns its place by delivering operationally critical information: account requirements, what the tool does and does not do, when to avoid it, return structure, citation guarantees, and latency. Front-loaded with the account prerequisite, which is essential for call success. No fluff or repetition.

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

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

With no output schema, the description fully compensates by explaining the return packet: verbatim evidence + confidence + source + fetched_at + citation_uri, plus gaps[] and contradictions[] as applicable. It also covers auth, fallback path, latency, and depth semantics. Given the tool's complexity and the absence of structured output metadata, this is a complete contextual picture.

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

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

Schema coverage is 100% for both params, giving baseline 3. The description adds value beyond schema: it reveals that depth:'thorough' requires a paid plan, clarifies the depth levels' effect on gap-recovery hops and contradictions[], and notes that question can be broad/multi-part because decomposition is inherent. This contextualizes parameter choices without duplicating schema text.

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

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

The description opens with a precise verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and contrasts it with open-web search. It clearly distinguishes from siblings by naming ask_pipeworx as the single-lookup alternative, and explains the research workflow (decomposition, parallel routing, findings packet).

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

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

Explicitly states when to use this tool: 'Best for broad/multi-part questions over structured data' with concrete examples. Provides clear exclusions: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' Also gives a fallback if not signed in: 'use ask_pipeworx instead — it works on every tier.'

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 indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral context: it fans out across multiple sources in parallel, soft-fails on patents due to sunset, and uses a GDELT→GNews fallback. It also lists the exact data returned. No contradictions with annotations. Slightly more detail on performance or caching would improve it.

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

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

The description is moderately concise with several sentences, but each earns its place by providing examples, guidance, and return structure. It front-loads the purpose with examples. Could be slightly more structured (e.g., bullet points), but it's efficient overall.

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 only 2 parameters, no output schema, and comprehensive annotations, the description thoroughly covers inputs, return fields (CIK, filings, fundamentals, patents, news, LEI), sources, and limitations (patents sunset, name restriction). It provides a complete picture for an agent to understand and use 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%, so baseline is 3. The description adds semantic value by clarifying that 'value' accepts ticker or zero-padded CIK, and explicitly states that names are not supported (requiring a prior step). This reduces ambiguity beyond the schema's description.

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 produces a 'full cross-source profile of a US public company in ONE parallel call' with example queries. It distinguishes from siblings by recommending it over chaining individual lookups, and its purpose is clearly differentiated from tools like 'compare_entities' 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 gives explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also notes that names are not supported and advises to 'use resolve_entity first if you only have a name.' This clearly tells when and when not to use the tool.

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

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

Annotations already 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 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral traits beyond these: no indication field, no queryable application_type, uppercase requirement, and field behavior differences. These are not covered by annotations, so description adds meaningful 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 somewhat lengthy but front-loaded with critical information (purpose, warnings, alternatives). Every sentence serves a purpose for correct usage, though it could be slightly more concise by combining related warnings. The structure prioritizes key constraints early.

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

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

Given the tool's complexity (query syntax, special fields, uppercase), the description covers all necessary context. It explains return values (approval status, sponsor, ANDA/NDA prefix) and warns about missing fields. The output schema exists but the description still adds value for result interpretation. It is complete for a complex 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%, so baseline is 3. However, the description adds significant meaning beyond the schema: it explains query syntax, field differences, uppercase requirement, common pitfalls, and provides examples. The param descriptions in the schema are detailed, but the description's warnings and context (e.g., NOT using openfda.generic_name) compensate richly.

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 finds FDA-approved drugs by brand name, active ingredient, or application number. It uses specific verbs and resources, and distinguishes itself from siblings like fda_drug_labels by specifying that it lacks indication data.

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

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

The description provides explicit guidance on when to use this tool versus alternatives (e.g., fda_drug_labels for conditions), warns about field selection (products.active_ingredients.name vs openfda.generic_name), requires uppercase input, and advises against using non-existent fields like application_type. It gives clear context and exclusions.

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

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

Annotations already cover read-only and non-destructive behavior. The description adds context about retry logic for natural multi-word reaction phrasing against MedDRA preferred-term order, and notes that FAERS reports do not establish incidence or causality. This goes beyond the annotation-provided safety profile.

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

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

The description is three sentences, front-loaded with the primary action and scope. Each sentence adds value, including the retry caveat and data limitation. No filler.

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

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

Given the high schema coverage, annotations, and presence of an output schema, the description sufficiently covers the tool's purpose and behavior. It could potentially mention how it relates to more specialized FAERS tools, but that is not necessary for basic 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 fully documents all three parameters. The description adds no additional parameter-level detail beyond restating search facets. 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 searches FAERS adverse event reports by drug name, MedDRA reaction term, or date range, and lists what it returns. This specific verb-resource pairing distinguishes it from sibling tools like fda_faers_trend or fda_event_counts.

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 on when to use the tool: searching FAERS reports by drug, reaction, or date range. It does not explicitly exclude alternatives or mention when not to use it, but the search scope is well-defined.

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 safe read operation. Description adds valuable context: text fields are capped, set_id preserved for full-label retrieval, and warning about delayed label publication. 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?

Front-loaded with core purpose, each subsequent sentence adds critical detail (contrast with sibling, query formats, return fields, caveat). No filler; every sentence earns its place.

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

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

With output schema present (likely detailed), description covers returned fields, limits, and an important temporal caveat. Complete for a read-only search tool with rich 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 has 100% coverage, so baseline 3. Description adds meaning by explaining query parameter syntax with examples (e.g., 'openfda.brand_name:"HUMIRA"', 'indications_and_usage:"rheumatoid arthritis"'), and specifies limit defaults to 5. 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?

Description clearly states it retrieves FDA drug labeling by drug name or indication, distinguishes from sibling tool fda_drug_approvals by noting that approvals endpoint lacks indications text, and lists returned content (indications, warnings, dosage, etc.). Verb+resource specific and contrasts with alternatives.

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 frames the tool as the one to use for 'what drugs are approved to treat <condition>', contrasts with fda_drug_approvals, provides query examples, and notes limitation of label publication lag. Clear when to use and when not.

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 important behavioral details: the multi-word fallback from ALL to ANY matching, the match_mode indicator in the response, and the free-text nature of recall reasons. These additions materially help the agent interpret results and avoid mistaking loose matches for precise ones.

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

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

The description is three sentences with no wasted words. The primary purpose and return values are front-loaded, followed by crucial behavioral caveats and domain-specific search advice. Every sentence earns its place.

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

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

Given the tool's moderate complexity, the description covers purpose, return fields, match behavior, and query strategy. The output schema handles return values, and annotations cover safety. No critical gaps remain for an agent to use the tool effectively.

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

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

The input schema already covers both parameters with 100% coverage, so the baseline is 3. The description adds helpful guidance on query interpretation (e.g., free-text reasons, substance vs. symptom search) but does not add new parameter-level syntax or semantics 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 a specific verb ('Search') and resource ('FDA drug recalls and enforcement actions'), and lists the returned fields (classification, date, reason, enforcement status). It distinguishes from sibling tools by specifying 'drug' recalls, differentiating from fda_food_recalls.

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

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

The description gives clear context for when to use the tool (searching drug recalls) and includes useful search-strategy guidance, such as using ALL terms with fallback to ANY and searching for the substance name when a symptom finds nothing. However, it does not explicitly name alternatives or exclusions, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. 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, idempotentHint, and destructiveHint false, covering safety. The description adds output context (top reactions, event trends) but does not disclose limits, pagination, or other behavioral traits. For a tool with strong annotations, a 3 is appropriate.

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

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

The description is two sentences, front-loaded with the action, and every word contributes to understanding. No filler or redundancy.

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

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

The description, combined with a comprehensive schema and output schema, covers the essential aspects of the tool well. It lacks explicit sibling differentiation, but given the rich structured data and annotations, it is sufficiently 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%, with both query and count_field fully described. The description's mention of 'reaction type, patient age, or outcome' merely restates examples already in the schema, adding no extra semantic value. 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 a specific action ('Aggregate adverse events') and resource ('by reaction type, patient age, or outcome'), and mentions return types. However, it does not explicitly distinguish from sibling tools like fda_faers_reaction_profile or fda_faers_trend, so it falls short of a 5.

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

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

The description implies usage for aggregation/counting but provides no explicit when-to-use or alternatives. The schema reference to 'Same syntax as fda_drug_events' is a pointer, but the description itself lacks guidance on selecting this tool over similar ones.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds important caveats that counts include duplicates, co-medications, and reporting bias, and are not event rates or proof of causation. This goes beyond annotations by clarifying data interpretation. It does not describe return format, but the caveat is significant.

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 filler. The first sentence states the core function, the second adds a necessary caveat. Both earn their place, and it 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?

The description covers the main output (reactions and counts) and a crucial caveat, but lacks parameter details and return structure. Given the absence of an output schema and 0% schema coverage, this is a noticeable gap. It is adequate for a high-level understanding but not fully complete 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 0%, and the description does not explain the four parameters (drug, limit, to_date, from_date) beyond their self-evident names. The dates and limit semantics are left unspecified, such as date format or default behavior. With such low schema coverage, the description should compensate but does not.

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: summarizing frequently co-reported FAERS reactions plus serious/non-serious report counts for a drug. The verb 'summarize' and specific resource ('FAERS reactions') make the purpose unambiguous. It distinguishes from siblings by focusing on reaction profile rather than signals or 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 description implies use for a drug's reaction profile but does not explicitly say when to use this tool over siblings like fda_faers_signal_summary or fda_faers_trend. It provides context about the data (spontaneous reports) but no explicit alternatives or exclusions. This is implied usage without direct guidance.

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

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

Beyond the annotations (readOnly, 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 indicate readOnly and idempotent. The description adds that it queries openFDA /food/enforcement and details return fields (reasons, classification, etc.), offering useful 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 concise sentences, front-loaded with the action, 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?

For a simple read-only tool with well-documented parameters, annotations, and no output schema, the description sufficiently covers purpose, scope, and usage differentiation.

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 and examples. The description adds minimal extra meaning; it mentions 'optional — omit for most recent recalls' which is already in 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 searches FDA food recall enforcement reports, listing specific fields (product recalls, reasons, classification, etc.), and explicitly distinguishes from sibling fda_drug_recalls.

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 advises use for food-safety/recall-history questions and differentiates from fda_drug_recalls, providing clear context. However, it could be more explicit 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, idempotentHint, and non-destructive behavior. The description adds transparency by stating that generics are excluded by default and results are sorted newest-first, which goes beyond the annotations.

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

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

The description is concise with no redundant sentences. It starts with the core purpose, then gives usage examples, and ends with return fields and exclusions. 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 no output schema, the description adequately specifies the return fields. It covers purpose, usage, and behavioral nuances. However, it does not mention pagination or rate limits, which are minor omissions for a simple 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 coverage is 100% with clear descriptions for all 3 parameters. The description does not add additional parameter information beyond what the schema provides, except for reaffirming the default exclusion of generics. 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 it returns the most recent novel drug approvals (NDA/BLA) with specific fields, and distinguishes itself from sibling tools fda_drug_labels and fda_drug_approvals by explicitly stating what it is not 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 provides explicit usage examples ('what is the most recent novel drug the FDA approved', 'latest FDA drug approvals') and excludes cases ('Not for label text (fda_drug_labels) or searching a specific known drug (fda_drug_approvals)').

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?

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds context about types of violations (CGMP, adulterated, unapproved claims), data source (fda.gov, keyless live data), and output components. 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?

Two concise sentences and a return-field list. Every sentence adds value, no redundant information. Front-loaded with purpose and examples.

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 2 parameters, no output schema, and safety annotations, the description fully covers how to use the tool, what results contain, and data provenance. 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 both parameters. Description adds examples and clarifies search scope (company, product, violation topic) and default behavior (omit for recent letters). Adds meaningful context 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?

Description clearly states it searches FDA Warning Letters, explains what they are (enforcement letters for violations), provides example queries, and lists return fields. Distinct from siblings like fda_drug_approvals or fda_food_recalls.

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 query examples ('FDA warning letters for <company>', 'recent FDA warning letters about supplements/devices') and notes to omit search for most recent letters. Does not explicitly mention alternative tools but 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 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?

The description discloses all behavioral traits: two modes, response format (leg prices, top_spreads_pp), safety fields (compatibility_warning cases), temporal alignment, and skipped cross types. This goes far beyond the annotations, which only state read-only, idempotent, and non-destructive.

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 well-structured with paragraphs, bullet-style lists, and bolded key terms. It front-loads the core purpose and efficiently covers edge cases. Could be trimmed slightly but is appropriately sized for the 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?

Despite having no output schema, the description fully defines the response structure (leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). Together with the parameter descriptions, it provides complete context for using this complex cross-venue tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the topic mode with concrete shortcut examples and clarifying the explicit mode parameters, making it a 4.

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

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

The description immediately states the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue 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 explicitly explains two modes (topic and explicit), provides a list of pre-mapped macros, and offers guidance on when spreads are meaningful vs. not, including compatibility warnings and temporal alignment.

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?

Annotations already declare read-only and idempotent behavior. The description adds valuable context: the internal cascade through multiple endpoints, graceful degradation of LEI/FIGI enrichment, source labeling for identifiers, and explicit reporting of unresolved identifiers. This is 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 long but well-structured: query examples first, then the main purpose, then detailed type-specific behavior. Every sentence adds value, though it could be tightened without losing essential information.

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

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

With no output schema, the description compensates thoroughly. It details return values for each type (SEC EDGAR IDs, LEI, FIGI, RxCUI, ingredient, brand), source labeling, unresolved handling, and graceful degradation—complete enough for an agent to understand what to expect.

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

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

Schema coverage is 100% with clear parameter descriptions. The description reinforces `value` semantics with examples (ticker/CIK/name for company; brand/generic for drug) and adds what each type returns (CIK, ticker, LEI, FIGI, RxCUI, etc.), enriching meaning beyond the schema.

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

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

The description clearly states the tool's function: resolving user-spoken names to canonical identifiers. It provides concrete query examples ('ticker for...', 'find the CIK for...') and lists supported entity types (company, drug), distinguishing it from siblings that likely consume those identifiers.

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

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

Explicit guidance is given: 'Use FIRST whenever you have a name but need an ID.' This defines the primary use case and implies when to use this tool over alternatives. It also notes that it replaces 2-3 manual lookups, further clarifying its role.

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.