Usda Fdc

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable behavioral context: default model (free), API key forwarding to Anthropic (BYO key, you pay), and return format (per-model {score, confidence, signals, raw_response} + combined view). 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 compact (one long sentence) but includes all essential information. It could be slightly better structured with bullet points or separate sections, but it's efficient and front-loaded with purpose.

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

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

Given 4 parameters (1 required), no output schema, the description covers purpose, parameters, behavior, return structure, and use cases. It is complete for the tool's complexity.

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

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

Schema description coverage is 100%, so schema already documents each parameter. The description adds practical context: default model is free, _apiKey enables Anthropic probing with cost implication, and context disambiguates entities. This enhances 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 probes LLMs for entity knowledge and scores visibility (0-100). It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on individual entities and specifying use cases (AI-marketing audits, pre-launch checks). The verb 'probe' and resource 'LLMs' are specific.

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

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

The description gives explicit use cases ('useful for AI-marketing audits...') and explains parameter triggers (default model, API key for Anthropic). However, it does not mention when NOT to use the tool or name alternative sibling tools for similar tasks, which would improve guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable context: routes to 4,552 tools, returns structured answers with citation URIs, and is fast. 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 well-structured with a clear opening directive, detailed scope, usage guidance, and examples. Every sentence serves a purpose; no extraneous 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 (6 params, 1 required, no output schema), the description is remarkably complete. It covers purpose, usage, behavioral traits, parameters, and alternatives, leaving no significant gaps for an agent to misinterpret.

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

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

Schema coverage is 100%, so the schema fully documents the question parameter and its aliases. The description adds value by providing example questions and explaining the type of input expected, which helps the agent formulate queries.

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: answering factual questions using authoritative data from thousands of sources, with a strong preference over web search. It distinguishes itself from sibling tools by naming ask_pipeworx_grounded and deep_research as alternatives for specific needs.

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

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

Provides clear when-to-use guidance (factual questions about real-world data) and when-not-to-use (though it notes the tool handles breaking news). It explicitly advises stepping up to grounded or deep_research for certain scenarios, giving concrete examples of appropriate queries.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context: refusal reasons (not_in_source, no_tool_match, etc.), cost implication (one extra LLM call), and evidence extraction behavior. No contradictions.

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

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

Front-loaded with key purpose and usage, then details. Moderately concise; each sentence adds value. Could be slightly tighter but effective.

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

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

Despite no output schema, description fully explains return values on success and failure, including specific refusal reasons. Complex tool with multiple siblings; covers essential behavioral and selection context.

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

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

Schema covers 100% of parameters with descriptions for each alias. Description does not add significant new meaning beyond the schema, but it references 'question' implicitly. Baseline 3 is appropriate as 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 explicitly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes it from ask_pipeworx by detailing its grounded extraction process. It clearly defines verb (answer), resource (data from 4,552 tools/1160 sources), and usage 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?

Provides explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on... Prefer ask_pipeworx for casual lookups.' Clearly states when to use and when not, with specific 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?

The description extensively documents behavioral traits beyond annotations: fan-out logic, response shapes, resolver contract with confidence levels, parent event extractor, news fallback mechanisms, safety short-circuits, and resolution-rule risk. Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are all consistent and the description adds significant 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 very long and includes many details that could be considered verbose. While it is structured with section headings and front-loaded with the main purpose, it could be more concise without losing essential information. For a complex tool, some verbosity is acceptable, but it still exceeds reasonable length.

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

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

Despite the lack of an output schema, the description thoroughly explains all return fields: market details (bid/ask/spread), analysis (model probability, edge), evidence keys, resolver contract (confidence, alternatives, suggestions), parent event extractor, news fields, and safety mechanisms. All important behaviors and edge cases are covered.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining default values (depth='thorough', include_raw=false) and providing context for the market parameter (slug, URL, question text). This enhances understanding 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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the inputs (slug, URL, question text) and provides example usage cases ('should I bet on X', etc.). It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on researching a specific bet with data fan-out.

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 examples: 'Use for...'. It also provides guidance on when to inspect market_match_confidence and when analysis may be suppressed (low confidence, closed markets, wide spreads). However, it does not explicitly compare to sibling tools or 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?

Annotations already declare readOnly, openWorld, idempotent, and not destructive. Description adds rich behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorted results by primary metric, and output format (paired data + citation URIs). No contradiction.

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

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

Front-loaded with example queries, then explains behavior, data sources, sorting, and output. Every sentence adds value; no filler. Concise yet comprehensive for the tool's complexity.

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

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

For a tool with no output schema, description adequately covers return values (paired data + citation URIs). Explains handling of fiscal year nuances and data sources for both entity types. Complete for a comparison tool with moderate complexity.

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

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

Schema coverage is 100%, so parameters are documented. Description adds significant meaning: specifies what data each type retrieves (e.g., revenue, net income for company; adverse-event counts for drug) and gives examples. This goes 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?

Description uses specific verb+resource ('compare', 'rank') and clearly states it does side-by-side comparison of 2-5 companies or drugs. It distinguishes from siblings by explicitly contrasting with sequential single-pack lookups, making the unique value clear.

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

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

Provides explicit when-to-use examples ('X vs Y', 'which is bigger', 'rank these companies') and instructs to prefer over sequential lookups. Does not explicitly mention alternatives for single entities (e.g., entity_profile), but the context is strong and sufficient for the tool's purpose.

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 significant context beyond annotations: requires account (free with paid tier for thorough depth), describes output packet structure (evidence, confidence, source, gaps[]), time expectation, and decomposition into parallel tool routing. No contradictions with readOnlyHint/idempotentHint/destructiveHint.

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

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

The description is thorough but slightly verbose; however, every sentence adds value. Front-loaded with account requirement and alternative. Could be slightly more concise but well-organized.

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

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

Given the tool's complexity, lack of output schema, and many siblings, the description fully explains purpose, limitations, use cases, and expected behavior. Leaves no critical gaps for an agent to understand invocation.

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

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

Schema coverage is 100%, and the description adds meaning: depth enum values explained (quick=3, standard=5, thorough=8), question as natural language broad/multi-part. No parameters are left unexplained.

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

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

The description clearly states the tool performs grounded multi-source research across structured data, distinguishes itself from open-web search, and gives specific use cases like 'compare X and Y's regulatory + financial exposure'. It also contrasts with 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 guides when to use (broad/multi-part structured questions) and when not (breaking news, colloquial topics), with alternative ask_pipeworx recommended for those cases. Mentions ask_pipeworx for single lookups and live news.

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

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

Annotations already indicate readOnly=true, idempotent=true, and destructive=false. The description adds that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed,' providing useful behavioral context beyond annotations.

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

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

The description is composed of three sentences, front-loading the purpose and providing examples. It is efficient but could be slightly more concise. Overall well-structured for quick comprehension.

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

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

Despite no output schema, the description fully explains what the tool returns (names, descriptions, schemas with examples) and when to use it. It covers usage guidance, parameter semantics, and behavioral details, making it complete for a discovery tool with high schema coverage.

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

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

Schema description coverage is 100% with each parameter having a description. The description mentions that query accepts natural language and lists aliases, and provides example values in the input schema's examples. However, it does not add significant extra semantics beyond the schema, warranting a baseline score of 3.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and distinguishes it from sibling tools like search_within or ask_pipeworx by focusing on tool discovery itself.

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 when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set.' It provides clear when-to-use guidance but does not explicitly state when not to use.

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

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

Annotations already indicate idempotent/non-destructive reads. The description adds significant behavioral context: parallel fan-out across multiple sources, specific return fields, soft-fail for patents, and accepted input formats. 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 detailed and well-organized, starting with example queries and structural guidance. Some redundancy (e.g., multiple examples) could be trimmed, but overall front-loaded and efficient for an AI agent.

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?

Completeness is high given no output schema: description enumerates all returned data types (CIK, filings, fundamentals, patents, news, LEI) with specific formats. Sufficient for an agent to understand inputs and outputs without needing external documentation.

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

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

Input schema describes parameters (type enum, value string). Description reinforces that 'value' can be ticker or CIK and explicitly states unsupported inputs (names). Since schema coverage is 100%, baseline is 3, but the description adds practical usage nuances, warranting a 4.

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

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

The description clearly states the tool's purpose: creating a cross-source profile for US public companies. It specifies verb ('profile') and resource ('US public company'), and differentiates from sibling tools like 'resolve_entity' by clarifying that names are not supported here.

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 this tool: 'ALWAYS PREFER over chaining single-pack...lookups when the user asks for a holistic view.' Also provides guidance on input types (ticker or CIK) and directs users to 'resolve_entity' if they have only a name.

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 destructiveHint=true and idempotentHint=true; description adds context by explaining purpose (clear stale/sensitive data), which is valuable 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 filler, immediately clear and efficient.

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

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

For a simple one-parameter tool with no output schema, the description fully covers purpose, usage, and relationship to siblings.

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

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

Schema coverage is 100%, so baseline is 3. Description mentions 'key' but adds no additional meaning 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 verb ('Delete') and resource ('memory by key'), and differentiates from sibling tools by mentioning pairing with 'remember' and 'recall'.

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 lists when to use (stale context, task done, clear sensitive data) and hints at alternatives via pairing, though no explicit 'when not to use' is given.

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 minor behavioral context (fetch, extract, emit) but no further constraints or side effects.

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 plus a bullet list of use cases, no wasted words, front-loaded with 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 2 parameters and no output schema, description fully explains purpose, mechanism, and output format ('standard llms.txt markdown format', 'single text blob').

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; description does not add additional semantic detail 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 uses specific verb 'Generate' on resource 'llms.txt file for any URL', clearly distinguishing from siblings like ai_visibility_check or scan_competitor_ai_presence.

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 lists use cases (getting client's site indexed, drafting for own project, auditing competitor), providing good context for when to use, though not specifying when not to.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no additional behavioral context beyond retrieving a record. No contradiction.

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

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

Extremely concise single sentence with no waste. However, it is slightly under-specified for a tool with optional parameters; a bit more detail would improve it.

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 simplicity (3 params, output schema exists), the description is minimally adequate. It does not mention optional format/nutrients filtering, but the schema covers those. Could be slightly more informative.

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 already describes all parameters (fdc_id, format, nutrients). The description only mentions 'by FDC id', which repeats the schema. No extra semantic value added beyond baseline.

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

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

Description clearly states 'Full food record by FDC id', specifying verb (get), resource (food record), and unique identifier (FDC id). This distinguishes it from sibling tools like list_foods (lists many) and search_foods (search).

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

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

No usage guidance is provided. The description does not indicate when to use this tool versus alternatives or specify any prerequisites or constraints.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds minimal behavioral context beyond 'USDA food group reference', which is content-focused rather than behavioral. It does not contradict annotations but adds little value beyond what is already structured.

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 concise at 4 words. It is front-loaded and to the point. However, it could be slightly more informative without sacrificing conciseness, e.g., mentioning the source 'USDA' is good but no action verb or result description.

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

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

Given the tool has no parameters and an output schema exists, the description need not detail return values. However, it lacks usage context, sibling differentiation, and any hint of what the output represents (e.g., a list of category names). It is minimally adequate but not complete for an agent to fully understand its role.

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 zero parameters, so schema description coverage is effectively 100%. The description does not need to add parameter details. The baseline for no parameters is 4, and the description meets this adequately by not introducing confusion.

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 'USDA food group reference (categories)' clearly indicates the tool returns a list of food group categories. The verb is implied by 'list' in the name and 'reference' in the description. However, it does not distinguish itself from sibling tools like 'list_foods' or 'search_foods', which limits clarity for an AI agent choosing between 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?

No usage guidance is provided. The description does not suggest when to use this tool versus alternatives like 'list_foods' or 'get_food'. An agent has no context on whether this tool is a prerequisite or how it relates to other food-related tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds the pagination aspect but no additional behavioral context like rate limits or data freshness. With strong annotations, the description provides minimal extra 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 a single, front-loaded sentence that directly states the tool's purpose. Every word earns its place 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 that there is an output schema and annotations, the description is adequate but minimal. It does not explain parameter interactions or provide details on how pagination works, though the basic purpose is clear.

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 60%, with three parameters having descriptions in the schema. The description does not add any meaning beyond the schema, so it earns the baseline score of 3.

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

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

The description 'Paginated browse of FDC foods' clearly states the action (browse/list), resource (FDC foods), and pagination feature. It distinguishes from the sibling tool 'search_foods' which implies a search/filter operation.

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 no guidance on when to use this tool versus alternatives like 'search_foods' or 'get_food'. No explicit context, prerequisites, or when-not-to-use cases 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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by specifying the default behavior (active subscriptions, include_inactive parameter) and listing the exact return fields, which are 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 long with no filler. The first sentence states purpose and return fields, the second provides usage guidance. 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?

Given the tool's simplicity (one optional parameter, no output schema), the description fully covers the purpose, return fields, default behavior, and usage context. It is complete enough for an agent to 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?

The input schema has 100% coverage with a description for the only parameter (include_inactive). The tool description does not add additional semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description starts with 'List the caller's active subscriptions', which is a specific verb+resource pair. It lists the return fields (id, type, params, etc.) and is clearly differentiated from sibling tools like subscribe and unsubscribe.

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

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

The second sentence explicitly recommends using this tool 'to review what you're monitoring before adding more or to find an id to cancel', providing clear context for when to invoke it. It does not state when not to use it, but the guidance is sufficient.

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

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

Annotations indicate a safe read operation (readOnlyHint=true, destructiveHint=false). The description adds no behavioral details such as error handling, default behavior, or response format beyond the existing 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 very concise (one sentence) and front-loaded with 'Convenience'. However, it sacrifices informativeness for brevity.

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 sibling tools and an output schema, the description is incomplete. It does not clarify the output structure, optional parameters, or relationship to other tools.

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

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

Schema description coverage is 50% (nutrient_numbers has a description). The tool description adds no additional meaning for either parameter. fdc_id lacks description in both schema and 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 'nutrient values only for a food' lacks a verb and does not explicitly state the action. It is essentially a restatement of the title. There is no differentiation from sibling tools like get_food.

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

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

The description implies use for nutrient-only retrieval but does not explicitly state when to use this tool versus alternatives such as get_food or search_foods. No usage scenarios 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?

Discloses rate limits (5 per identifier per day), cost (free, doesn't count against quota), and team reading habits (digests daily, affects roadmap). Annotations only indicate non-readonly/destructive, so description 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?

Description is concise yet comprehensive: front-loaded with purpose, then usage scenarios, then tips. 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?

For a feedback tool with 3 parameters (one nested object), no output schema, the description covers all necessary context: rate limits, quota, format, and team processes. No gaps remain for an agent to misuse 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 coverage is 100%, but description enriches each parameter: explains 'type' enum values in detail, describes 'context' as optional structure with pack/tool/vertical, and adds specificity for 'message' (be specific, 1-2 sentences, 2000 char max).

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: sending feedback (broken, missing, needed) to the Pipeworx team. It specifies types like bug, feature, data_gap, praise, distinguishing it from sibling tools that perform queries or actions.

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

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

Provides explicit when-to-use guidance for each feedback type (bug, feature/data_gap, praise) and includes usage tips like describing in terms of tools/packs and not pasting end-user prompts.

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 (readOnlyHint, idempotentHint), the description reveals data source (CF analytics-engine), no PII, and caching durations (5min-1h). This adds valuable behavioral context about freshness and privacy.

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: one sentence for main purpose, bullet list for use cases, then technical details. Every sentence adds value, and it's concise without being sparse.

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 parameter, rich annotations, and no output schema, the description covers all necessary context: purpose, use cases, data source, caching, and parameter semantics. Nothing is missing.

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

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

The description adds semantic guidance for the 'window' parameter: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enriches the enum values already in the schema.

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

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

The description clearly states the tool returns trending tools, packs, and call volume over a window, using specific verbs like 'Returns'. It distinguishes from siblings by focusing on aggregate call data rather than tool discovery or search.

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

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

Three explicit use cases are listed: discovering hot data sources, confirming canonical tools, and aligning use case with agent demand. It implicitly suggests when to use but does not explicitly state when not to use or name 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, all consistent. The description adds substantial behavioral details beyond annotations: the core algorithm (monotonicity violations, partition-sum), semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder slugs, >20% placeholder returns null), and fill check (CLOB depth, realizable_edge_pp). This fully informs the agent of the tool's internal logic and constraints.

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

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

The description is front-loaded with the main purpose and then structured into clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). While detailed, it is not overly verbose given the complexity. Minor redundancy exists (e.g., repeating 'partition_check' explanation), but overall it's well-organized and informative.

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 of the tool (two modes, no output schema), the description covers all critical aspects: mode selection, algorithm details, edge cases (placeholder slugs, similarity threshold), return fields, and fill-check logic. It also mentions a related tool for custom sizing, ensuring the agent has sufficient context to invoke the tool correctly.

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

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

The input schema has 100% description coverage, but the description adds significant meaning beyond the schema. It explains the two modes in detail with examples (event slugs like 'fed-decision-may-2026', topic seeds like 'Fed rate decision'), clarifies that no args triggers a trending scan, and describes the output structure of each mode. This enriches the parameter understanding considerably.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the resource (Polymarket) and method, and distinguishes three modes (no args, event, topic) with distinct behaviors, making it highly specific and differentiating from siblings.

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

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

The description provides explicit recommendations for when to use each parameter mode, including 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. It also references the sibling tool polymarket_fill_risk for custom sizing. However, it lacks explicit contrast with other directly related tools like polymarket_edges or polymarket_edge_tracker, which could be mentioned for edge-case guidance.

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

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

Beyond annotations, the description discloses caching (1h KV-level), explains that fed candidates are excluded from ranking, details diagnostics for empty segments, and clarifies assumptions like slippage and no trading fees, providing 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 very detailed and well-structured but overly long (several paragraphs), which may hinder quick comprehension. While every sentence adds value, it could be more concise without losing essential information.

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

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

Given the absence of an output schema, the description thoroughly explains the response structure, including segments, fields like edge_pp_net and kelly_fraction, diagnostics, and knobs, leaving no key aspect unaddressed.

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, the description adds practical context, such as explaining that slippage_pp accounts for Polymarket's bid/ask spread and that min_partition_leg_kelly is needed because partition arbs have zero parent-level Kelly, enhancing parameter understanding.

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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' and further emphasizes its purpose for daily betting decisions, clearly distinguishing it from general market scanning tools.

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

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

The description provides clear usage context: 'Built for what should I bet on today' and explains what knobs like min_liquidity and max_spread_pp do, but does not explicitly contrast with sibling tools like polymarket_arbitrage, leaving some ambiguity about when to use which.

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, non-destructive. The description adds rich behavioral context: response structure (tracked, expired, snapshot_dates), trend classification, decay rate, data gaps due to cache-miss, and 60-day TTL. 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 well-structured with clear sections (RESPONSE, LIMITS) and front-loads the core purpose. It is somewhat verbose but each sentence adds value; could be slightly more concise but remains 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 structure (tracked[], expired[], snapshot_dates[]) and their fields, including trend classification and decay calculation. It also covers limitations thoroughly. Highly complete.

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

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

Schema coverage is 100% with parameter descriptions. The description adds default values, clamping, and window family context, enhancing semantics beyond the schema. Baseline 3, extra context earns a 4.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry. It differentiates from siblings like polymarket_edges by focusing on historical persistence and decay rates. The specific question 'how long has this edge existed and is it shrinking?' gives precise context.

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

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

The description implies when to use it (when edge persistence matters) and contrasts fresh vs. aged edges. It provides limits and data gap explanations but does not explicitly state when not to use it or name alternatives beyond the sibling list.

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, not destructive. The description adds substantial behavioral context: walks the ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, and for basket mode returns theoretical vs realizable sum, capture ratio, profit, per-leg details, thin_legs, max_clean_notional, forced_directional_risk. 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 around 150 words, well-structured with clear sections for purpose, modes, return fields, and usage guidance. It is front-loaded with the key verb and resource. Every sentence adds value, though it could be slightly tightened 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?

Given the complexity (two modes, many return fields, no output schema), the description is highly complete. It enumerates all return fields for both modes, explains the risk of partial baskets and forced directional risk, and includes usage context. No output schema means the description must carry full burden of return value specification, which it does thoroughly.

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 4 parameters with descriptions. The tool description elaborates on parameter behavior: explains market vs event modes, side options with defaults, and size_usd interpretation (spend vs target proceeds vs settlement notional). It adds contextual meaning beyond the schema descriptions, justifying a score above baseline 3.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', specifying two distinct modes (single-market and basket) and explicitly distinguishing from sibling tools polymarket_arbitrage and polymarket_edges by recommending use before acting on their signals.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and explains the rationale (theoretical overround on thin books is not capturable, partial basket fills convert arb into unhedged directional position). This provides clear when-to-use and why-not-to-use guidance.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description discloses detailed behavioral traits: the two modes, response structure (leg prices, spread), safety fields (compatibility_warning triggers), temporal alignment requirements, and skipped leg-pair counters. It explains why spreads may be meaningless, adding context that annotations cannot capture.

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 with a purpose sentence, then mode explanations, response layout, and safety field details. It is front-loaded with the core purpose. While somewhat lengthy, every sentence contributes essential information, making it efficient for its complexity. A slight trim could improve conciseness, but it remains clear.

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 3 parameters, no output schema, and high complexity (two modes, compatibility checks, temporal alignment), the description covers all necessary aspects: it explains response fields, safety warnings with specific conditions, and counters for skipped comparisons. It is complete for an agent to correctly invoke and interpret the tool's output.

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

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

Schema description coverage is 100%, so the schema already documents parameters. The description adds significant value by explaining the interaction between topic and explicit tickers, providing examples, and clarifying that explicit parameters override the topic-mapped side. This enriches understanding beyond the basic property 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 uses specific verbs and resources: 'Cross-venue spread between Kalshi and Polymarket'. It clearly distinguishes two modes (topic shortcuts vs explicit tickers) and explicitly states that it computes spreads for the same resolving question. The purpose is unambiguous and distinct from siblings like polymarket_arbitrage or polymarket_edges, even though those are not directly compared.

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

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

The description provides explicit guidance on when to use each mode (topic vs explicit tickers) and includes crucial warnings: compatibility warnings when bet shapes are non-equivalent or events are semantically unrelated, and temporal alignment caveats. It explicitly states 'Real cross-venue spreads are rarer... most pre-mapped topics return compatibility_warning today', telling the agent when not to rely on the tool.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds behavior for empty key (list all), scoping, and pairing. No mention of limits, but adequate for a read-only tool.

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

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

Two sentences, front-loaded with action. Every sentence adds value without fluff. Efficient and structured.

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

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

For a simple retrieval tool with 1 optional param and no output schema, the description covers behavior, pairing with siblings, and scoping. Complete and self-contained.

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. Description adds context: omitting key lists all keys, key retrieves specific value. Provides usage nuance 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 uses the specific verb 'Retrieve' and resource 'a value previously saved via remember', clearly distinguishing 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 states when to use the tool ('look up context... without re-deriving'), and implicitly contrasts with remember/forget. Could be improved by stating when not to use, 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it details the return fields (source, citation_uri, raw payload), explains that mark_read modifies state to flag events as read, and confirms polling works fine. There is no contradiction.

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

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

The description is concise, with no wasted words. It front-loads the main purpose, then efficiently covers return fields, filtering, mark_read behavior, and an alternative endpoint. Every sentence adds value.

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

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

Given 5 optional parameters and no output schema, the description covers the core functionality: what is returned, filtering, and mark_read. It mentions an alternative endpoint for scripts. It does not explicitly discuss pagination or limit behavior, but the schema covers limit details. Overall, it is sufficiently complete for a read-only tool with good annotations.

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

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

Schema coverage is 100% with parameter descriptions. The description adds examples (e.g., type 'sec_8k', since ISO timestamp) and clarifies the effect of mark_read. This goes beyond what the schema provides, justifying a score above the baseline of 3.

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

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

The description clearly states the tool retrieves fired events from a subscription feed, specifying the verb 'pull' and the resource 'fired events from your subscription feed'. It distinguishes itself from siblings like list_subscriptions by focusing on fired events and return fields (source, citation_uri, raw payload).

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 guidance on filtering by type and since, using mark_read to manage read state, and mentions polling and an alternative URL for scripts/dashboards. It lacks explicit exclusions or when-not-to-use, but the context is sufficient for typical use.

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

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

Annotations already indicate readOnly=True, idempotent=True. Description adds context: fans out to three sources, soft-fail for USPTO, GDELT→GNews fallback. 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?

Single paragraph, front-loaded with example queries, every sentence adds value, concise given the complexity of multiple sources and fallbacks.

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

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

No output schema, but description explains return structure: changes[] grouped by source, total_changes, citation URIs. Also covers source-specifics and error handling. Distinguishes from sibling.

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% so baseline 3. Description adds meaning: explains type only supports company, since format with examples, value can be ticker or CIK, and usage tip for since.

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

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

Description clearly states it returns a change feed for a company, with example queries. It distinguishes from sibling entity_profile by explicitly telling when to use that instead.

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

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

Provides explicit when-to-use guidance via example queries and explains when not to use it (use entity_profile for static profiles). Also describes fallback logic between GDELT and GNews.

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 context beyond annotations: scoping by identifier, persistence details (24 hours for anonymous). No contradictions with annotations (idempotent, not destructive).

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

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

Three concise sentences, front-loaded with purpose, minimal repetition, 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?

Adequate for a simple 2-param tool with no output schema. Covers purpose, usage, persistence, and pairing with related tools.

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% parameters with descriptions. Description reinforces key-value nature and provides examples, adding 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?

Clearly states the tool saves data for reuse later. Distinguishes from siblings by referencing 'recall' 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?

Provides explicit when-to-use guidance ('discover something worth carrying forward') and mentions pairing with other tools. Could clarify when not to use (e.g., transient vs permanent storage).

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

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

Annotations already cover readOnly, idempotent, etc. Description adds value by stating it cascades through several endpoints and replaces manual lookups, giving insight into performance and internal behavior.

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 common queries, then concise guidance and type details. Every sentence adds value, though could be slightly more streamlined.

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

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

No output schema, but description provides clear return details for each type including citation URIs. Missing error handling, but for 2-param tool it is largely complete.

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

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

Schema covers parameters fully. Description enhances with examples of acceptable values per type and details of what is returned, adding 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 the tool resolves names to canonical IDs with specific examples (ticker, CIK, RxCUI). It distinguishes itself from siblings by advising to use it first when needing an ID, and lists supported types with outputs.

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

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

Provides explicit when-to-use scenarios and supported types. Does not explicitly list when not to use, but implication is clear. Alternatives like entity_profile are not directly mentioned but context implies usage before 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?

Discloses that it probes each entity using 'ai_visibility_check', and describes the output structure (score, confidence, signal density). Annotations already mark it as read-only and idempotent, so the description adds useful behavioral context 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?

Three sentences, front-loaded with purpose, no redundancy. Every sentence adds value.

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

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

Given no output schema, the description adequately explains the return format (ranked list with score, confidence, signal density). Covers purpose, usage, parameters, and internal behavior sufficiently for an 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%, but the description adds key context: first entity is the 'subject' for narrative, rest are competitors. Also clarifies optionality of models and the condition for _apiKey. This goes beyond the 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?

The description clearly specifies the verb 'compare', the resource 'AI visibility across multiple entities', and the action of ranking and surfacing most/least recognized. It distinguishes from sibling tool 'ai_visibility_check' which appears to be single-entity.

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

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

Provides a concrete use case ('competitive AI-marketing audits') and an illustrative question. However, it does not explicitly state when not to use this tool or mention alternatives like 'compare_entities' or 'ai_visibility_check' for single entity.

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?

Disclosed partial failure behavior, timing (5-30s), and 'sources_failed' key. Consistent with annotations; adds significant behavioral context beyond 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?

Single paragraph with front-loaded purpose, detailed data sources, usage guidance, and behavior. 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?

Despite no output schema, description thoroughly covers return fields, error handling, and ecosystem scope. Combined with annotations, provides complete information for agent decision.

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

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

Schema coverage is 100%, but description adds default version behavior and scoped package acceptance, providing extra semantics beyond the schema.

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

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

Description clearly states it performs a composite check on npm packages, listing specific data sources (deps.dev, bundlephobia). It uses a specific verb-resource combination and distinguishes from siblings by specifying npm ecosystem and composite nature.

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 provides usage examples ('is X safe / popular / small') and states when not to use (non-npm packages), directing to fallback alternatives (deps.dev:version directly).

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds return fields (FDC id, description, data type, publication date) but does not detail pagination or sorting behavior, which are in the schema.

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 cover purpose and key features without fluff. Every sentence adds value.

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

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

Given 7 parameters and an output schema, the description covers search scope, filters, and return fields. It omits pagination details but output schema likely compensates.

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 all 7 parameters with 100% coverage. The description adds context (e.g., 'name, brand, or ingredient' for query) but does not significantly extend schema details.

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

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

The description clearly states the tool searches USDA Food Data Central by name, brand, or ingredient, distinguishing it from siblings like get_food (retrieval by ID) and list_foods (no query).

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 lists filter options (data type, brand owner) but does not explicitly state when to use this tool over alternatives. However, the context implies searching vs. listing or getting specific items.

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

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

Goes beyond annotations by detailing the embedding model (BGE-base-en), similarity measure (cosine), window size (500-char overlapping), and character cap (200K chars with truncation flag). All annotations (readOnly, idempotent, etc.) are consistent with the description.

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

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

Dense but well-structured, front-loading the main purpose. Five sentences cover purpose, usage, behavior, and pairing. No redundant information, 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?

Given no output schema, description adequately covers return format (top-N passages with offsets and scores) and behavior (model, cap, pairing). Lacks exact output structure but sufficient for an agent to understand what to expect.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by clarifying that 'text' is a previously fetched record and provides query examples (e.g., 'supply-chain risk'), enhancing understanding 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 performs 'semantic search INSIDE a fetched record' with specific verb and resource. It distinguishes from siblings by pairing with ask_pipeworx_grounded and differentiating 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?

Explicitly advises using when record is too big for prompt, saves context, and returns passages with offsets. Mentions pairing with ask_pipeworx_grounded. Could be improved with explicit when-not-to-use, but current guidelines are clear and actionable.

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?

Description says 'Create a new subscription' implying a non-idempotent write operation, but annotations set idempotentHint=true (indicating side-effect-free repeatability). This is a direct contradiction, warranting a score of 1 per the guidelines.

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 with front-loaded purpose and detailed examples. While comprehensive, it is somewhat lengthy but every sentence adds value.

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

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

Given the complexity (3 params, nested objects, enums), the description covers all aspects: type options, parameter structures, delivery details, and prerequisites. No output schema is present, but the description clarifies return value.

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 description adds significant meaning beyond the schema: it explains each type with example params, delivery channel constraints (sms cap, webhook HMAC), and requirements. Schema coverage is 100%, but the description enriches understanding.

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

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

The description states the tool creates a proactive monitoring subscription and returns the subscription id. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description explains when to use the tool (for live-data event stream subscriptions), requirements (Pipeworx OAuth account), supported types, and delivery channels. However, it does not explicitly state when not to use it.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds valuable context: it returns categorized questions with tool calls, draws from a live catalog, and explains the parameter behavior. 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 trigger phrases, explains the return structure concisely, and covers usage in a few sentences. Every sentence adds value without unnecessary repetition.

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

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

Given no output schema, the description fully explains the return format (category-bucketed example questions with tool/argument shapes) and usage scenarios. It is complete and actionable for an 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 a description of the topic parameter. The description adds example values but does not provide significant additional meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states that the tool returns category-bucketed example questions with exact tool and argument shapes, and lists many trigger phrases. It distinguishes itself from sibling tools like ask_pipeworx by positioning itself as the onboarding entry point.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to use the topic parameter. It could improve by also stating when not to use this tool, but the positive guidance is strong.

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: ownership enforcement, deactivation vs deletion, and preservation of historical events for 'recent_alerts'. This aligns with the annotations (destructiveHint: false) and provides valuable detail.

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 core action ('Cancel a subscription by id') and efficiently convey ownership and persistence behavior. 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 tool's simplicity (single parameter, no output schema, no enums), the description fully covers the tool's purpose, constraints, and side effects. It also references 'recent_alerts' for historical data, completing the context.

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

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

The schema already describes the 'id' parameter as 'Subscription id (uuid) returned by subscribe.' The description does not add new information beyond restating the source of the id, so it meets the baseline with no extra value.

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

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

The description clearly states the tool's action (cancel a subscription by id) and explicitly distinguishes it from deletion by specifying that the row is deactivated, not deleted. The title 'Unsubscribe from Alerts' further clarifies the context.

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

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

The description provides ownership enforcement ('you can only cancel your own subscriptions'), which guides proper usage. It implicitly contrasts with deletion by noting historical events remain, but doesn't explicitly compare with sibling tools like 'subscribe' or 'list_subscriptions'.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint off. The description adds beyond annotations by detailing the return information (verdict types, structured form, actual value with pipeworx:// citation, percent delta) and explaining that it replaces multiple calls, providing full 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 relatively long but well-structured. It starts with trigger phrases, states the purpose, then provides scope and return details. Each sentence serves a purpose, though some minor trimming could be done 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?

Given the tool's simplicity (single parameter, no output schema), the description is complete. It explains what the tool does, when to use it, what it returns, and its scope. The annotations and context signals are adequate, and no 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?

There is only one parameter ('claim') with 100% schema description coverage. The schema already describes the parameter as a natural-language factual claim. The description enhances it by providing example claims (e.g., 'Apple's FY2024 revenue was $400 billion') and specifying the expected format, adding 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's purpose: fact-checking natural-language claims against authoritative sources, specifically company-financial claims. It provides trigger phrases like 'Is it true that…' and 'fact check', and distinguishes from sibling tools by specifying its domain (company-financial claims via SEC EDGAR + XBRL).

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: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also notes that it replaces 4-6 sequential calls, implying efficiency benefits. However, it does not explicitly state when not to use it (e.g., for non-financial claims), though the scope is implied.

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