Openfda

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

Annotations indicate read-only, idempotent, and non-destructive; the description reinforces this and adds behavioral details: default free model, BYO key for Anthropic, per-model and combined return structure, cost implications. 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 4-5 sentences, front-loaded with the primary action, then parameter details, return format, and use cases. No redundant information; each 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 4 parameters, no output schema, the description compensates by detailing the output structure (per-model {score, confidence, signals, raw_response} + combined view) and use cases. It covers all necessary context for correct invocation.

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

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

Schema covers 100% of parameters with descriptions; the description adds further clarity by explaining the default model when 'models' omitted, that `_apiKey` is only for Anthropic, and giving examples for 'context'. This adds 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 uses specific verbs ('Probe', 'score visibility') and identifies the resource ('LLMs', 'business/brand/product/topic') and unique output ('score 0-100 per model'). It clearly distinguishes from sibling tools like ask_pipeworx, entity_profile, and scan_competitor_ai_presence by focusing on AI visibility scoring rather than Q&A or deep profiling.

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 states when to use the tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains conditions for optional parameters (e.g., `_apiKey` needed for Anthropic). It implies when not to use (e.g., if grounded answers needed, use siblings), but could explicitly exclude alternatives. The context is clear but not fully comprehensive.

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, destructiveHint. Description adds value by explaining it returns structured answers with citation URIs and routes questions internally. No contradiction with annotations.

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

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

Front-loaded with 'PREFER OVER WEB SEARCH', well-structured with purpose, examples, and guidelines. Every sentence adds value, though could be slightly more concise.

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

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

Covers purpose, usage, and return format (structured answer with citation URIs) adequately. Without output schema, description compensates well. Missing details on error handling or multi-question capability.

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. Description adds examples and clarifies aliases, but no critical new meaning beyond what 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?

Description clearly states it answers factual queries using 3,745 tools and 884 sources, with specific examples like SEC filings and FDA data. It distinguishes from web search and other tools by emphasizing preference over web search for structured 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?

Explicitly tells when to use (e.g., for factual questions, 'what is', 'look up', etc.) and states preference over web search. However, it does not mention when not to use or contrast with sibling tools like ask_pipeworx_grounded.

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

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

Annotations already indicate read-only, open-world, idempotent. Description adds extra LLM cost, refusal reasons, and evidence extraction, adding significant value 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?

Front-loaded with purpose, structured with return format and refusal reasons. Slightly long but efficient for its 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 no output schema, description covers behavior, failure modes, and trade-offs comprehensively. Sufficient for high-stakes use.

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

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

Schema description coverage is 100% with aliases explained. Description mentions 'question' but does not add new semantics beyond schema, 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?

Clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads.' Describes the routing, extraction process, and distinguishes from sibling ask_pipeworx.

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 advises use when answers will be quoted/cited/acted on and to prefer ask_pipeworx for casual lookups. Provides clear when-to and when-not-to-use criteria.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is clear. The description adds extensive behavioral details: fan-out patterns per classifier, response shapes, resolver contract (market_match_confidence, alternatives), parent event extractor, news fallback fields, safety mechanisms for low-confidence, closed markets, wide spreads, and resolution-rule risk. This goes well 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 extremely verbose (over 800 words in a single paragraph). While it front-loads the core purpose, the extensive details on classifiers, fan-out examples, response shapes, resolver contract, etc., make it overly long. Better structuring with sections would improve conciseness.

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

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

Given the tool's complexity (multiple classifiers, fan-out patterns, response fields, resolver logic, parent events, news fallback, safety checks, resolution rules) and the lack of an output schema, the description provides comprehensive coverage. An agent can understand exactly what the tool does and how to 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?

All three parameters have full schema descriptions (100% coverage), so baseline is 3. The description adds significant context: examples for market input (slug, URL, question), default and behavior for depth ('quick' vs 'thorough'), and explanation of include_raw impact on response size. This adds 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 researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and output (evidence packet + comparison). It distinguishes from siblings like polymarket_edges by focusing on a single bet research, and gives explicit use cases.

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: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. While it doesn't list when not to use or name specific alternatives, the context is clear enough for an agent to select this tool over others.

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 read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial value by detailing data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. 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 moderately concise but well-structured. It front-loads trigger phrases, then explains the tool's operation, per-type details, and results. While not extremely terse, every sentence contributes useful 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?

Given the tool's complexity (two distinct data types, multiple entities) and the absence of an output schema, the description fully covers input, behavior, and output format. It explains what data is returned (paired data with URIs) and how results are sorted, providing complete context for an AI agent to 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?

With 100% schema description coverage, the schema already documents both parameters. However, the description adds meaningful context by explaining the types (company vs drug) with concrete examples and clarifying the expected format for values (tickers/CIKs vs drug names). This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs in a single parallel call. It uses specific verb phrases like 'compare' and provides trigger examples such as 'X vs Y' or 'rank these companies'. It distinguishes itself from siblings like entity_profile or fda_drug_approvals by emphasizing parallelism and efficiency.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a strong usage directive. It gives concrete query examples and explains the data sources and sorting behavior, helping the agent decide when to invoke 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?

Adds rich context beyond annotations: parallel routing, citation format (pipeworx://), gaps array for unanswered facets, and time estimate (15-60s). No contradiction with readOnlyHint, openWorldHint, or idempotentHint.

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

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

Every sentence adds value: core function, mechanism, usage guidance, prerequisites, time estimate. No fluff, efficiently 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?

Despite no output schema, the description explains the return format (structured findings with evidence, confidence, source, gaps). It also covers prerequisites (account, plan), making it self-contained for appropriate use.

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 already covers both parameters with descriptions. The description adds minimal extra meaning, like 'broad/multi-part is fine' for question, but does not significantly enhance understanding 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 performs grounded multi-source research in one call, decomposing questions into sub-questions and routing to many tools. It distinguishes from siblings like ask_pipeworx, which is for single 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?

Explicitly advises use for broad or multi-part questions and directs to ask_pipeworx for simple lookups. Also mentions account and plan requirements, setting clear expectations.

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: it states that results include full input schemas with curated examples and are 'ready to call directly, no second schema lookup needed.' This transparency about what the tool returns and its efficiency is excellent.

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

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

The description is a single paragraph that front-loads the main purpose. It lists many domains which, while slightly verbose, aids user understanding. Every sentence adds value, though the list could be more compact. Overall it is efficient and well structured.

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

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

Given the tool's discovery purpose, 6 parameters (all described), high schema coverage, and no output schema, the description fully explains what the tool does, when to use it, and what it returns (names, descriptions, schemas, examples). Annotations cover safety. No gaps remain.

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

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

Input schema coverage is 100%, so baseline is 3. The description repeats parameter aliases already in the schema but adds value by providing natural language examples of queries (e.g., 'analyze housing market trends') and clarifying limit defaults (20, max 50). This is helpful but not significantly 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 it finds tools by describing the data or task, using a specific verb ('discover') and resource ('tools'). It lists many example domains and distinguishes itself from sibling tools by emphasizing it returns schemas ready to call, which is not done by other tools.

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

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

The description explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance, though it does not name specific alternatives for other scenarios. The context of browsing/searching is well conveyed.

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 the fan-out behavior across multiple data sources (SEC, XBRL, USPTO, news, GLEIF) and specifies exactly what is returned. It also notes a soft-fail condition for patents ('USPTO PatentsView API sunset May 2025 — soft-fails until reactivated'). Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description complements them well. Minor deduction for not mentioning potential latency from the parallel 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 dense but well-structured. It starts with concrete example queries (front-loading the most critical information), then states the core function, lists return fields, and ends with important caveats. Every sentence adds value; nothing is redundant. Despite length, it earns its space.

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

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

Given the tool's complexity (multi-source fan-out) and the absence of an output schema, the description provides a thorough listing of returned fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). It also addresses the patents soft-fail scenario. This is sufficient for an AI 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%, so baseline is 3. The description adds value by explaining that the 'type' parameter currently only supports 'company' (though schema already has an enum) and that 'value' accepts ticker or CIK. More importantly, it explicitly excludes names and directs users to 'resolve_entity' for name resolution. This goes 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 uses clear verbs ('Tell me about', 'research', 'brief me') and specifies the exact resource: 'full cross-source profile of a US public company.' It distinguishes itself from sibling tools like 'resolve_entity' by noting that names are not supported here. The purpose is unambiguous and immediately actionable.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Additionally, it provides clear input constraints: 'Pass ticker or zero-padded CIK — names not supported (use resolve_entity first if you only have a name).' This gives perfect guidance on when to use this tool versus 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, so the description's addition of 'Returns approval status, sponsor, and application details' adds behavioral context about the response structure without contradicting annotations.

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

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

The description is a single clear sentence with 20 words, front-loading the purpose and including key examples. 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?

Given the presence of an output schema and thorough annotations, the description covers the main purpose and input examples. Minor gaps like pagination or error handling could be mentioned, but overall it is sufficient for a read-only, idempotent 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% and both parameters are described in the schema. The description adds example queries but does not significantly enhance understanding beyond what the schema already provides.

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

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

The description clearly states the tool's function: 'Find FDA-approved drugs by brand name, generic name, or application number'. It uses a specific verb ('Find') and resource ('FDA-approved drugs'), and the examples differentiate it from siblings like fda_drug_events or fda_drug_labels.

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 example queries but does not explicitly state when to use this tool versus alternatives (e.g., fda_drug_labels for label text or fda_drug_events for adverse events). Usage context is implied but not clarified.

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-only, idempotent behavior. Description adds return fields (event counts, reaction types, seriousness, dates). Does not disclose pagination behavior beyond schema or rate limits.

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?

Single sentence concisely states action, resource, and filters. Front-loaded with verb and resource.

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 low complexity, full schema coverage, annotations, and output schema, the description sufficiently covers search functionality and return fields.

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

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

Schema coverage is 100% with detailed descriptions and examples. Description adds minimal new meaning beyond listing filter dimensions already in schema examples.

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 searches adverse event reports with filters by name, reaction type, or date range. It distinguishes from siblings like fda_drug_approvals and 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?

No explicit guidance on when to use this tool versus alternatives like fda_event_counts for counts or fda_drug_labels for labeling. The description does not mention 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=true, idempotentHint=true, destructiveHint=false, indicating a safe, read-only tool. The description adds behavioral context by specifying the types of data returned (indications, warnings, dosage, etc.), which is useful beyond the annotations.

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

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

The description is two concise sentences with no filler. The first sentence states the core action, and the second lists return categories efficiently. 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?

An output schema exists, so the description doesn't need to detail return structure. It lists all relevant return categories. Combined with the schema and annotations (readOnly, idempotent), the description provides a complete picture for an agent to use 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%, so the input schema fully documents both parameters (query and limit). The description only mentions 'by drug name' which maps to the query parameter, but adds no additional 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 tool retrieves drug safety information from FDA labels by drug name, listing specific return categories (indications, warnings, etc.). This distinguishes it from sibling tools like fda_drug_approvals (approvals) and fda_drug_events (adverse events).

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

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

The description implies usage for drug label information but does not explicitly state when to use this tool versus alternatives like fda_drug_approvals or fda_drug_events. No exclusion criteria or prerequisites are mentioned.

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, providing safety transparency. The description adds that it returns classification, date, and status, but does not elaborate on rate limits, authentication, or other behavioral nuances beyond the annotations.

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

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

The description is two sentences, front-loaded with the action, and contains no superfluous information. Every sentence adds value: the first explains the purpose and method, the second describes the output.

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 presence of an output schema and well-documented parameters, the description is fairly complete. It covers the tool's purpose, search method, and return fields. However, it could briefly differentiate from similar tools like fda_drug_events or mention the query format complexity, which is partially in the schema examples.

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 both parameters, including examples for query. The description reiterates search by drug name or reason but adds no new parameter semantics beyond what the schema already provides.

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

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

The description clearly states it searches FDA drug recalls and enforcement actions by drug name or reason, using a specific verb and resource. The name 'fda_drug_recalls' aligns with this purpose and distinguishes it from sibling tools like fda_drug_approvals and fda_drug_events.

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

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

The description implies usage for drug recall searches but provides no explicit guidance on when to use this tool versus alternatives. No when-not-to-use or specific contexts are mentioned, leaving it to the agent to infer based on the name alone.

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. The description adds that the tool returns aggregated counts and trends, which goes beyond the annotations. No contradictions, and the behavioral context is sufficient.

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

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

Two concise sentences that front-load the verb and resource. Every word contributes meaning; no fluff.

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

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

With a complete input schema, output schema present, and annotations covering safety, the description adequately summarizes the tool's function. It could mention potential limitations like pagination, but overall 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 descriptions for both query and count_field. The description adds thematic grouping examples but does not significantly extend beyond what the schema already provides. Baseline of 3 is appropriate.

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

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

The description clearly states the tool aggregates adverse events by specific grouping fields (reaction type, patient age, outcome) and returns top reactions and trends. This distinguishes it from the sibling tool fda_drug_events, which likely returns raw event 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 implies usage for aggregation but does not explicitly state when to use this tool versus alternatives like fda_drug_events. No when-not-to-use or exclusions are provided.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds minimal behavioral context beyond deletion, such as 'clear sensitive data'. Does not contradict 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, no wasted words. First sentence defines action, second provides usage guidance. Ideal conciseness.

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

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

With one required param, no output schema, and annotations covering safety, the description completes the picture with purpose and usage guidance. Could mention return behavior (e.g., confirmation) but not necessary for such a simple 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?

The single parameter 'key' is fully described in the schema (100% coverage). The tool description adds no new information about the parameter beyond restating 'by key'.

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 ('Delete') and resource ('a previously stored memory by key'). It also implicitly distinguishes from siblings like 'remember' and 'recall' by being the delete 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, task done, or to clear sensitive data. Mentions pairing with remember/recall. Lacks explicit when-not-to-use or alternatives, 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, providing safety guarantees. The description adds behavioral detail: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format', which goes beyond annotations. No contradictions. However, it doesn't disclose potential timeout or fetch failures, but given annotations, this is acceptable.

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

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

The description is two sentences plus a use case list, with the primary action clearly stated first. Every sentence adds value: purpose, process, output, and usage contexts. No fluff.

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

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

Given the tool has only two parameters, no output schema, and comprehensive annotations, the description sufficiently covers what the tool does and how to use it. It could mention error handling or rate limits, but for a simple read-only tool, the level of detail is 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?

The input schema has 100% coverage with descriptions for both parameters (url and max_links). The description adds context about fetching the page and output format but does not enhance parameter understanding beyond the schema. Baseline 3 is appropriate since the schema is self-sufficient.

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 an llms.txt file for a given URL, specifying the verb 'Generate' and the resource 'llms.txt file'. It explains the process (fetches page, extracts metadata) and the output format, making the purpose unambiguous. While it doesn't explicitly differentiate from siblings like 'ai_visibility_check', the unique function is well-articulated.

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

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

The description provides three specific use cases (client site indexing, drafting for own project, auditing competitor) giving clear context for when to use. It doesn't explicitly state when not to use, but the examples cover common scenarios. Sibling tools like 'scan_competitor_ai_presence' might overlap, but the description's clarity mitigates confusion.

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. Description adds value by specifying return fields and default behavior (active subscriptions with optional include_inactive).

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: first states purpose and returns, second provides usage guidance. No fluff, front-loaded with key 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 list tool with one optional param and robust annotations, the description is fully adequate, listing return fields and usage guidance.

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 for the single parameter. Description implies default behavior (only active) but does not add substantial meaning 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 'List the caller's active subscriptions' with a specific verb and resource, and enumerates returned fields, distinguishing it from siblings like subscribe and unsubscribe.

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

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

Explicitly advises when to use: 'before adding more or to find an id to cancel.' Provides clear context, though does not explicitly list alternatives.

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

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

Annotations already indicate write operation (readOnlyHint=false) but not destructive. The description adds behavioral traits: rate-limited to 5 per identifier per day, free, doesn't count against quota, and that the team reads digests daily. This goes 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 but comprehensive, covering purpose, usage, constraints, and tips in a few sentences. It is well-structured and front-loaded with the primary action.

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

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

Given the tool's simplicity (no output schema, few parameters), the description covers all necessary context: when to use, what to include, rate limits, and quota impact. It is complete for effective use.

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 parameters. The description adds context about describing issues in terms of Pipeworx tools/packs, but this is usage guidance rather than parameter semantics. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: to send feedback to the Pipeworx team. It lists specific categories (bug, feature, data_gap, praise) and instructs what to include. This distinguishes it from sibling tools, none of which are feedback tools.

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

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

The description explicitly says when to use the tool (for bugs, features, data gaps, praise) and what not to do (don't paste the end-user's prompt). It also mentions rate limits and that it's free, providing comprehensive usage guidance.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds valuable context: no PII, data from CF analytics-engine, and caching behavior (5min-1h). 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, front-loaded with purpose, followed by use cases and transparency details. Every sentence adds value with no 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?

Given no output schema, the description mentions the return types (top tools, top packs, total call volume) but doesn't specify the exact structure. Still adequate for a simple tool with one parameter.

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 'window' is fully described in the schema (enum, default, usage advice). The description adds no additional meaning beyond the schema, 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 returns trending top tools, packs, and call volume over configurable windows. It distinguishes itself from siblings like 'discover_tools' by focusing on real-time agent usage 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?

Three explicit use cases are provided, guiding the agent on when to use this tool for discovering hot data sources, confirming canonical tools, and checking use case alignment. This is excellent 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 declare read-only, idempotent, open-world, non-destructive. Description adds detailed behavioral context: walks child markets, checks ordering, computes partition_check, uses semantic anchor with Jaccard similarity, filters placeholder slugs, and performs fill check against live CLOB depth. 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 thorough but somewhat verbose. However, it is well-structured with clear section headers (REQUIRES, SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and every sentence provides essential information. A minor reduction in length could improve conciseness.

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

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

Despite lacking output schema, the description comprehensively explains the response structure (opportunities, partition_check, fill_check details), including edge cases like skipped_low_similarity and placeholders_filtered. It also references a sibling tool for additional functionality, making it complete 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 already describes both parameters (event and topic) with coverage 100%. Description adds semantic meaning: event slug vs full URL, topic as seed question, and explains the mode switching behavior. This goes beyond the schema's basic descriptions.

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

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

The description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes two distinct modes (event and topic) with specific usage, and differentiates from sibling tools like polymarket_edges and 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 states required parameters and that calling with no args fails. Provides clear guidance on when to use event vs topic, including scenarios where cross-event catches patterns single-event misses. Also advises on when not to trade (realizable_edge_pp ≤ 0) and directs to polymarket_fill_risk for custom sizing.

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

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

The description goes well beyond the annotations (readOnlyHint, idempotentHint, etc.) by detailing caching behavior (1h at KV level), response structure (by_segment, fed_candidates, _diagnostics), and why segments may be empty. It explains the 24h-move warning and the logic behind model families. This provides comprehensive behavioral transparency.

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

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

The description is long but well-structured with clear sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.) and front-loaded purpose. Every sentence adds value given the tool's complexity. However, some redundancy could be trimmed without losing clarity.

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

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

With 9 parameters and no output schema, the description thoroughly explains the response structure, caching, filtering knobs, and diagnostic fields. It covers edge cases and provides enough context for a complex tool. Sibling differentiation is indirectly handled via the specialized purpose.

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

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

Although schema coverage is 100%, the description adds significant value by explaining parameter nuances: slippage_pp mentions zero fees but bid/ask depth, min_partition_leg_kelly clarifies why min_kelly does not apply to partitions, and max_spread_pp/min_liquidity are tied to 'tradeable-edge' concept. Each parameter gets extra context 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 purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is built for 'what should I bet on today' and distinguishes itself by avoiding the need to page through hundreds of markets. The three response segments are explicitly defined, providing a precise scope.

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 this tool (discovering opportunities for daily betting) and mentions tradeable-edge knobs and Fed exit criteria. However, it does not explicitly contrast with siblings like polymarket_edge_tracker or polymarket_arbitrage, nor does it specify when not to use it. Thus, usage guidance is clear but lacks direct 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 indicate read-only, idempotent, not destructive. The description adds context: snapshot TTL (60 days), decay computed from daily closes not intraday, and limitations like gaps in data. It does not contradict annotations and provides extra behavioral 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?

The description is moderately dense but well-structured: starts with purpose, then details response fields, then limitations. Every sentence adds information, though it could be slightly more concise. It front-loads the main question answered.

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 thoroughly explains the response structure (tracked with time-series, expired with lifespan, snapshot dates with data gaps) and limitations (TTL, start date). It covers all necessary context for an agent to understand what the tool returns and its constraints.

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 reinforces meaning: 'days' as lookback with default/max, 'window' as snapshot family with defaults. It also explains the response structure (tracked, expired, snapshot_dates) which adds semantic 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 precisely states the tool's purpose: providing edge persistence and decay telemetry from snapshots, distinguishing between fresh and old edges. It uses specific verbs like 'answers how long has this edge existed' and contrasts with sibling 'polymarket_edges' by focusing on time-series analysis.

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 implicitly guides when to use this tool (to distinguish age of edges) and hints at not using it for current edge values (as it focuses on historical persistence). However, it does not explicitly mention alternatives or when not to use it, leaving room for ambiguity.

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 read-only, non-destructive, idempotent. Description adds detailed behavioral context: walks the ladder, returns top_of_book, vwap_fill_price, slippage, shares filled, verdict; for baskets, explains theoretical vs realizable sums, capture ratio, profit, thin legs, forced directional risk. Warns that partial basket fills convert arb to unhedged position. Contradiction: false.

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 long but well-structured with clear mode divisions and return value listing. Every sentence adds value, though slightly verbose. Front-loaded with purpose and requirements.

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, so description fully covers return fields for both modes (top_of_book, vwap_fill_price, slippage, etc. for single-market; theoretical_sum, realizable_sum, capture_ratio, profit, per-leg details, thin_legs, max_clean_notional, forced_directional_risk for basket). Also explains edge cases and dominant loss mode, making it complete for a complex tool.

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

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

Schema coverage 100% but description adds value: clarifies that size_usd means 'max spend on buys, target proceeds on sells' for single-market vs 'settlement notional S' for basket; explains default side detection logic for basket mode. Enhances understanding beyond schema descriptions.

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

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

Starts with a specific verb+resource ('Realizable-vs-theoretical edge check against live CLOB order-book depth') that clearly states what the tool does. Explicitly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use it.

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?

Clearly states requirement of one of 'market' or 'event', explains single-market vs basket modes with default behaviors, and provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also warns about partial fills and directional risk, giving alternative 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 mark the tool as read-only and idempotent. The description adds extensive behavioral context: two operational modes, compatibility warnings for non-equivalent bet shapes or semantically unrelated events, temporal alignment checks, counters for dropped comparisons, and detailed output structure. 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 thorough but slightly verbose; however, every sentence adds necessary information. Structure is logical: purpose, modes, response fields, safety warnings. Could be slightly tighter without losing value, but acceptable 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?

Given the complexity (3 parameters, no output schema), the description is remarkably complete. It explains the response format, safety fields, temporal alignment, and edge cases. The absence of an output schema is fully compensated by detailed behavioral descriptions.

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 adds significant value by explaining how the 'topic' parameter maps to 10 macro shortcuts, how explicit tickers override topics, and the semantics of each mode in relation to tool 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?

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket, distinguishing it from any sibling tool. It specifies the verb 'cross-venue spread' and the resource (two prediction markets), with precise detail on modes and safety fields.

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 describes two usage modes (topic shortcuts vs explicit tickers), explains when each is appropriate, and warns that pre-mapped topics often trigger compatibility warnings, setting realistic expectations. Also explains how to interpret compatibility and temporal alignment fields.

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 provide readOnly, idempotent, non-destructive hints. Description adds scoping (anonymous IP, key hash, account ID) and pairing hints, going beyond annotations without contradiction.

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

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

Two sentences, no wasted words, front-loaded with core action, very concise.

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, annotations cover safety, description fully explains retrieval, listing, scoping, and related tools; no output needed.

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

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

Input schema has 100% coverage with one optional parameter. Description adds context on omitting key to list all, adding 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 retrieves a value via 'remember' or lists all keys if omitted, differentiating from siblings '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 when to use (look up stored context) and mentions pairing with remember/forget; could be more detailed on alternatives but 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?

The description discloses the mark_read behavior (flags returned events as read), which is a state modification. However, annotations include readOnlyHint=true, indicating no modifications. This is a contradiction between description and annotations. Per rules, score is 1 for 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 coherent paragraph, well-structured with the main purpose first. It efficiently includes essential information without redundancy. A slight structural improvement could be using bullet points for clarity, but it is already concise.

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 lack of an output schema and five optional parameters, the description fully explains what the tool returns (source, citation_uri, payload), how filtering works, the side effect of mark_read, and even provides an alternative access method. It is comprehensive for agent understanding.

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 basic descriptions. The description adds value by providing examples (e.g., 'sec_8k' for type) and clarifying the effect of mark_read. It also explains the combined use of type and since for filtering.

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 pulls fired events from a subscription feed and returns recent alerts. It specifies the returned fields (source, citation_uri, raw event payload) and mentions filtering options (type, since). This distinguishes it from siblings like list_subscriptions or subscribe, which manage subscriptions rather than retrieve alerts.

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

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

The description includes explicit usage guidance: notes that polling works fine and provides an alternative endpoint for scripts/dashboards. It implies the tool is for retrieving alerts from a persisted feed. It does not explicitly state when not to use it, but 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 indicate read-only, idempotent, non-destructive behavior. The description adds further transparency about fanning out to multiple sources, fallback behavior (GDELT→GNews), and soft-fail for USPTO. It does not mention rate limits, but overall adds valuable 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 somewhat lengthy but every sentence serves a purpose. It is front-loaded with example queries and then provides functional details. It could be slightly more concise, but does not contain unnecessary information.

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

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

Given the tool's complexity (multiple sources, fallback, parameter formats, return structure) and the absence of an output schema, the description does a good job covering return structure (changes[], total_changes, citation URIs) and source behavior. It could be more detailed on the exact output schema, but it is functionally 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?

The input schema covers all 3 parameters with descriptions. The description adds meaning by explaining the `since` parameter format in detail (ISO date or relative shorthand with examples), and clarifies that `value` can be a ticker or CIK. 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 provides a change feed for a company over a time window, with specific example queries. It distinguishes itself from the sibling tool entity_profile by noting the alternative for static profiles.

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

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

The description explicitly tells when to use this tool vs entity_profile, and provides example queries that indicate appropriate use cases. It also implies not to use it for static profile needs.

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

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

Beyond annotations (idempotentHint=true, destructiveHint=false), description reveals scoping by identifier, persistence duration (24 hours for anonymous), and that it's a write operation. 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 4 sentences with clear front-loading of purpose. Every sentence adds value: purpose, usage cues, storage details, and pairing guidance. 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?

Given the simple nature (key-value store with 2 params), description covers purpose, usage, persistence, scoping, and related tools. No output schema needed. Fully sufficient for agent to select and invoke correctly.

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

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

Schema already describes both key and value with types and constraints. Description adds naming conventions (e.g., 'subject_property', 'target_ticker') and example values, enhancing usability beyond 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 'Save data the agent will need to reuse later' and provides concrete examples like resolved ticker, target address, user preference. It distinguishes from siblings by referencing recall and forget as paired tools.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and gives examples of when to use. Also mentions pairing with recall and forget, and notes scoping by identifier and persistence differences between authenticated and anonymous sessions.

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 context beyond annotations: it states that each call cascades through multiple lookup endpoints internally (replacing manual lookups), mentions auto-disambiguation for companies, and specifies citation URIs in the output. All annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) are consistent.

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 action and examples, then details supported types with bullet points. It is somewhat verbose but appropriately so given the complexity of two entity types and their different return structures. Every sentence adds useful information.

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

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

Given the tool has 2 parameters with 100% schema coverage, no output schema but good annotations, the description fully explains inputs, outputs, and behavior. It covers supported types, input variations, return fields, and internal cascading. Nothing essential is missing for an agent to use it correctly.

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

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

Schema coverage is 100%, so baseline 3. The description enhances parameter meaning by detailing accepted input formats (ticker, CIK, or name for company; brand or generic for drug) and explaining what each type returns (ticker, CIK, company_name for company; RxCUI, ingredient, brand for drug), adding value beyond the schema's brief 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 resolves a name to a canonical identifier, with specific examples like ticker, CIK, RxCUI. It uses a specific verb 'resolve' and resource 'entity', and distinguishes from sibling tools by instructing 'Use FIRST whenever you have a name but need an ID.'

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID' and provides examples of user queries. It does not explicitly mention when not to use it or compare to sibling tools, but the context is clear and it explains the tool's role as a prerequisite for other 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=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral details: it probes each entity with ai_visibility_check, ranks by score, and surfaces the most/least recognized. It also describes output format (ranked list with score, confidence, signal density), which goes 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, no fluff, front-loaded with main purpose. Every sentence adds value and the structure is efficient.

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

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

Given 4 parameters (1 required), high schema coverage, no output schema, the description sufficiently explains return format and tool behavior. It covers the comparative nature, probing mechanism, and output details, making it complete for this complexity.

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

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

Schema description coverage is 100%. The description adds value by explaining the 'entities' array: first entry is the 'subject' and rest are competitors, and provides an example for 'context' parameter ('B2B SaaS', 'Boston restaurant'). This extra context improves parameter understanding 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 compares AI visibility across multiple entities side-by-side, using specific verbs like 'compare', 'probe', and 'rank'. It distinguishes itself from sibling tool ai_visibility_check by explicitly mentioning it probes each entity with ai_visibility_check, implying it is the comparative version.

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

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

The description provides explicit use cases ('useful for competitive AI-marketing audits') and an example question ('does Claude know about us as well as our competitors?'). It implicitly suggests using ai_visibility_check for single entities, but does not explicitly state when not to use this tool.

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

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

Beyond annotations (readOnly, openWorld, idempotent, destructive=false), the description adds significant behavioral details: composite check with two external sources, partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list timeouts. It also lists the return fields, providing transparency on what the agent can expect.

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

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

The description is well-structured and concise despite covering many aspects. First sentence states purpose, second gives usage, third lists return fields, fourth explains ecosystem scope, fifth addresses timing and errors. Every sentence earns its place, and the information is front-loaded with the key 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 no output schema, the description fully details the return structure (summary block, per-advisory detail, links, alternative versions). It covers edge cases (partial failures, timing, scoped packages) and ecosystem limitations. For a two-parameter tool, this is comprehensive and leaves little ambiguity.

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 value by noting that scoped packages are accepted for the package parameter and that version defaults to latest when omitted. It also contextualizes the parameters within the composite check, but doesn't add extensive new syntax details 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 it is a composite check for deciding whether to add an npm package, specifying the verb 'scan_dependency' and resource 'npm package'. It distinguishes from siblings by being a composite of deps.dev and bundlephobia, and explicitly mentions the use case: 'is X safe / popular / small' or 'what does adding lodash cost me'.

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

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

The description explicitly says 'Use whenever an agent asks...' and provides clear context for when to use this tool vs alternatives. It mentions NPM ecosystem only in v1 and that other ecosystems fall under deps.dev:version directly. It also addresses partial failures and timing, giving comprehensive guidance.

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

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

The description provides rich behavioral details beyond the annotations: it mentions the embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), similarity metric (cosine), character limit (200K chars), and truncation behavior. This far exceeds the minimal safety profile indicated by readOnlyHint and idempotentHint.

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 adds details in a logical order. Every sentence adds value, though it could be slightly tighter without losing clarity.

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

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

Despite lacking an output schema, the description fully explains what the tool returns: 'top-N passages with character offsets and similarity scores'. Combined with input constraints and behavioral details, this provides a complete picture for the agent.

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 all three parameters described. The description adds some context (e.g., default limit of 5, example queries) but does not significantly expand beyond what the schema already conveys. 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 tool name and title clearly indicate semantic search within a source. The description explicitly states 'Semantic search INSIDE a fetched record' and provides a specific use case: when a record is too large for the prompt. It also mentions a paired sibling tool (ask_pipeworx_grounded), differentiating it from other search tools.

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

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

The description tells when to use the tool ('when the record is too big to cram into the prompt') and how it pairs with ask_pipeworx_grounded. However, it does not explicitly state when not to use it or list alternatives beyond the sibling 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 indicate readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral details: requires Pipeworx OAuth, delivery constraints (email validation, SMS verification and 10/day cap, webhook signing and auto-disable after 10 failures), and returns a subscription id. 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 front-loaded with the main purpose and is well-structured with clear sections. However, it is somewhat verbose; for example, the delivery channel descriptions are repeated in both the main text and the schema description. Still, every sentence adds value and the length is justified by 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?

Given the complexity (3 parameters, nested objects, no output schema), the description is exceptionally complete. It covers all subscription types with example params, all delivery channels with constraints, account requirements, rate limits, auto-disable behavior, and the return of a subscription id. No critical information is missing.

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

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

Schema coverage is 100%, providing a baseline of 3. The description enriches every parameter with concrete examples, constraints, and behavioral context for each subscription type and delivery channel, far exceeding the schema's minimal descriptions.

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

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

The description explicitly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It uses a specific verb and resource, and clearly distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description provides strong usage context, including account requirements, supported types, and delivery channel options. However, it does not explicitly define when to use this tool versus alternatives like list_subscriptions or unsubscribe, which are present in 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds context beyond annotations by explicitly stating the output structure (category-bucketed example questions with exact tool+argument shape) and the effect of the optional topic parameter. 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 well-organized: front-loaded with common queries, then details on output, then usage guideline. Every sentence serves a purpose. Slightly verbose but not wasteful. Could be tightened, 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 no output schema, the description fully explains the return format: category-bucketed example questions and the exact tool+argument shape. It also covers the optional parameter behavior. For a tool with one optional parameter and no output schema, this is comprehensive.

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

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

Schema coverage is 100% and the schema description already explains the optional topic parameter. The description adds value by explaining the default behavior (full spread without topic) and that specifying a topic focuses the results, which goes beyond the schema's simple 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 is highly specific: it states the tool is the 'onboarding entry point' for an agent, lists multiple natural language queries, and explicitly contrasts with other tools by being the first step. It clearly identifies the verb (suggest), resource (questions), and scope (what Pipeworx can do).

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains when to pass the optional topic parameter vs. omit for full spread. No guidance on alternatives is needed because this tool is positioned as the entry point.

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 that the row is deactivated (not deleted) and historical events remain via 'recent_alerts', adding context beyond annotations. It aligns with annotations (readOnlyHint=false, destructiveHint=false) and provides a clear behavioral model.

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 action, no redundant words. Every sentence adds value: first states action, second adds important nuance about deactivation.

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

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

Given the simple tool (1 param, no output schema), the description covers the action, parameter, ownership, behavioral outcome, and historical data availability. No gaps remain.

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

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

With 100% schema coverage for the single 'id' parameter, the description adds no new semantic value; it merely restates 'by id'. Baseline 3 is appropriate as the schema already documents the parameter fully.

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

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

The description uses the verb 'Cancel' with the resource 'subscription by id', clearly distinguishing it from siblings like 'subscribe' and 'list_subscriptions'. It also specifies ownership enforcement, making the action 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 implies usage when cancelling a subscription, but does not explicitly state when not to use it or suggest alternatives. The context of ownership and behavioral outcome is clear, providing adequate guidance for selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral details: uses SEC EDGAR+XBRL, returns verdict types, structured form, actual value with citation, and percent delta. Extends beyond annotations without contradiction.

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

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

Description is moderately concise with front-loaded examples and clear segmentation. Every sentence adds information, though the 'Replaces 4-6 sequential calls' could be considered slightly verbose. Still efficient 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?

Without output schema, the description thoroughly details return fields (verdict types, structured form, actual value, citation, delta). It covers the tool's limitation (v1 company-financial claims) and hints at extensibility. Complete for a single-parameter tool with rich behavioral needs.

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 describes the 'claim' parameter with 100% coverage. Description adds value by providing examples of valid claims ('Apple's FY2024 revenue...') and the supported domain (company-financial via SEC), clarifying usage beyond the schema's generic 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 uses specific verbs like 'verify', 'confirm or refute' and clearly identifies the resource as 'natural-language claim verification against authoritative sources'. It distinguishes from siblings by stating it replaces 4-6 sequential calls, which clarifies its unique role.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and notes the v1 scope limited to company-financial claims. Lacks explicit exclusion of non-financial claims, but provides clear context for when to use.

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