Nass

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

Annotations indicate read-only, idempotent, open-world, non-destructive behavior. The description adds context: cost implications (free default, BYO key for Anthropic), API key passthrough, and per-model result structure, which are not covered by annotations.

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

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

Three well-structured sentences with no wasted words. Purpose, usage, and behavior are front-loaded, making the description efficient and easy to parse.

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

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

Despite no output schema, the description fully explains input parameters (including conditional requirements) and output structure. It provides sufficient detail for an agent to correctly invoke and interpret results.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds meaning beyond schema by noting default model, cost implications, and return format (score, confidence, signals, raw_response, combined view), enhancing agent 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 clearly states the tool's function: probing LLMs for knowledge about an entity and returning a visibility score. It specifies default model, optional Anthropic integration, and output format, making it distinct from sibling tools like 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?

The description mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and conditions for using the API key. However, it does not explicitly differentiate from sibling tools or indicate 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 indicate read-only, idempotent, and open-world. The description adds valuable detail: the tool routes questions, fills arguments, and returns structured answers with pipeworx:// citation URIs. No contradictions.

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

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

The description is front-loaded with the key preference directive. It is comprehensive but not overly verbose; each sentence adds value. Slightly long, but appropriate given the tool's breadth.

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

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

Given the tool's complexity (3,774 tools, no output schema), the description provides thorough context: what it queries, how it works, examples. It fully compensates for the absence of an output schema.

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

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

Schema coverage is 100% with descriptions for all 6 parameters (all aliases for 'question'). The description reinforces that these are aliases and provides examples, adding meaning beyond the schema by explaining the natural language input and routing behavior.

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

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

The description clearly identifies the tool as a fact-answering system that routes questions to 3,774 tools across 895 sources. It specifies the types of data (SEC filings, FDA, FRED, etc.) and contrasts with web search, distinguishing it from similar tools like deep_research.

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 'PREFER OVER WEB SEARCH' and lists example queries (e.g., 'current US unemployment rate'). It covers when to use but could be improved by noting scenarios where this tool is inappropriate, such as subjective or creative requests.

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 and idempotentHint=true. The description adds crucial detail: it extracts answers using ONLY the tool result, returns explicit refusal reasons (not_in_source, no_tool_match, etc.), and describes the success object shape. This goes beyond annotations by explaining the refusal behavior and the constraint of using only tool results.

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 key purpose and immediately distinguishes from sibling. It is relatively long but every sentence adds value (cost, use cases, return format). Could be slightly tighter (e.g., combining the two sentences on routing), but overall well-structured.

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

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

Given no output schema, the description fully explains the return format, including both success and refusal cases with exact field names and refusal reasons. It also explains the underlying process (routing, argument filling, extraction). Combined with 100% parameter coverage, it leaves no critical gaps 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% and all parameters are aliases for 'question'. The description does not add new meaning beyond what the schema provides—it reiterates that 'question' is the natural language query. With full schema coverage, baseline 3 is appropriate.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' and explicitly contrasts with ask_pipeworx for casual lookups. It specifies when to use: whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts. The verb 'ask' combined with 'grounded' indicates a focused, safe retrieval.

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

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

Explicitly states to prefer ask_pipeworx for casual lookups, and provides concrete use cases where grounded mode is required (financial verdicts, legal claims, medical lookups, public statements). Also notes it costs one extra LLM call, giving a clear cost-benefit trade-off.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds extensive behavioral context: fan-out examples, response shapes, resolver contract, parent event extractor, news fallback fields, safety short-circuits, illiquid spread handling, and resolution-rule 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?

Description is long but densely packed with useful information. Front-loaded with purpose and examples, then logically organized by response shapes, safety, and risk. Slightly verbose but every section earns its place given complexity.

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

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

No output schema, so description fully explains return fields: market, analysis, evidence, resolver contract, parent_event, news fields, and behavior in edge cases. Covers fan-out logic, safety short-circuits, and resolution-rule risk comprehensively.

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%; description adds significant meaning beyond schema: explains market accepts slug/URL/question, depth enum (quick vs thorough), include_raw (summarized vs full payloads with size estimates). Provides examples and clarifies default behavior.

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

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

Description starts with specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It then details the process, and the tool is clearly distinct from siblings like polymarket_edges or polymarket_arbitrage, which are about aggregated edges or arbitrage.

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

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

Explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Also provides when-not-to-use guidance via safety behaviors (low-confidence short-circuit, closed markets, wide spreads) and explains when to inspect resolver fields before trusting analysis.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description supplements by specifying data sources (SEC EDGAR for companies, FAERS for drugs) and sorting behavior, adding useful behavioral context without contradictions.

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

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

The description is well-structured and front-loaded with examples and core function. It efficiently packs information but could be slightly more concise 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 complexity and lack of output schema, the description adequately explains the return format (paired data, citation URIs, sorted results) and data sources, covering all essential information for an agent 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?

Schema coverage is 100% (both parameters fully described). The description adds value beyond schema by explaining what data each type fetches and the expected format (tickers for company, drug names for drug), enriching parameter meaning.

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

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

The description clearly defines the tool as performing side-by-side comparisons of 2-5 companies or drugs, with specific verb 'compare' and resource 'entities'. It explicitly distinguishes itself from sequential lookups and sibling tools like entity_profile, making its purpose unambiguous.

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

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

The description provides explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and gives natural language examples that trigger the tool. It implicitly tells the agent when to use this tool (comparison) and when not (single entity lookup), covering usage context well.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds significant behavioral context: verbatim evidence, confidence, source, fetched_at, and pipeworx:// citation per finding, explicit gaps[] for unanswerable facets, decomposition and parallelism, expected wait time (15-60s). No contradictions.

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

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

Description is 4 sentences, efficiently front-loaded with the core purpose, then details, usage guidance, and prerequisites. Every sentence adds value, 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 lacking an output schema, the description thoroughly explains what the tool returns (structured findings packet with evidence, confidence, source, gaps). It covers complexity, parallelism, and timing, making the tool's behavior fully understandable for an AI 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 has 100% coverage for both parameters. The description adds extra meaning: depth is explained ('quick=3, standard=5 (default), thorough=8 (paid plans)'), and question is described as natural language with decomposition emphasis. This adds value 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 states the tool's purpose: 'Grounded multi-source research in ONE call.' It explains that it decomposes questions into sub-questions, routes them to 3,774 tools in parallel, and returns a structured findings packet. It distinguishes from sibling ask_pipeworx, which is a single lookup.

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

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

Explicitly states when to use: 'Use for broad or multi-part questions.' Provides an explicit alternative: 'use ask_pipeworx for single lookups.' Also notes prerequisites: 'Requires a Pipeworx account (sign in via GitHub at https://pipeworx.io/signup); depth:"thorough" requires a paid plan.'

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 and destructiveHint=false. The description adds value by explaining the return format: 'Returns the 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.' This complements the annotations well.

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, starting with the verb-resource goal, then listing use cases and return behavior. While a bit long, every part adds value. Front-loaded with essential 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 the tool's simplicity as a meta-tool, the description adequately covers when to use, what it returns, and parameter aliases. No output schema needed as the return format is described. Minor gaps like pagination are not critical.

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

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

Schema description coverage is 100% with detailed param descriptions. The description adds a summary of aliases and the limit default/max, but this is mostly redundant with the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It explicitly distinguishes from sibling tools by advising to call this first when exploring tool options, not just getting one answer.

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

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

The description provides explicit usage guidance: '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 (not just one answer).' This helps the agent decide when to use this tool versus specific siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral detail: the tool fans out in parallel across multiple sources, notes that the USPTO PatentsView API sunset in May 2025 and will 'soft-fail until reactivated,' and specifies the exact data returned per source. No contradiction with annotations.

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

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

The description is long but efficiently structured: it opens with canonical example queries, states the preference rule, then enumerates the sources and specific return fields. Every sentence earns its place with no filler, making it easy to scan.

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

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

Despite lacking an output schema, the description comprehensively details the return structure: CIK, company_name, recent_filings (with URI format), fundamentals (specifying exact fields and sort order), patents, news, and LEI. It provides enough context for an agent to understand the output without surprises.

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

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

Schema coverage is 100% with both parameters described. The description adds meaning beyond the schema by clarifying that 'type' only supports 'company,' and 'value' accepts ticker or CIK but not names, including the fallback instruction to use resolve_entity. This additional context elevates the score above baseline.

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

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

The description opens with concrete example queries and clearly states the tool returns a 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from siblings like deep_research (more extensive), compare_entities, and resolve_entity by emphasizing breadth and single-call aggregation.

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

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

Explicitly tells when to use: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also explicitly states when not to use: 'Names not supported — use resolve_entity first if you only have 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 no new behavioral traits beyond confirming deletion. No contradiction.

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

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

Two sentences, front-loaded with action, no unnecessary words.

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

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

For a simple one-parameter delete tool with no output schema, the description provides sufficient context on action, rationale, and 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% of parameter with description; description adds no extra meaning beyond what 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?

Description states 'Delete a previously stored memory by key' – specific verb and resource, and distinguishes from siblings '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 says when to use: 'when context is stale, the task is done, or you want to clear sensitive data' and suggests pairing with 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?

The description explains the tool's behavior: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown format. It also notes the output is a text blob ready for site root. This adds value beyond the annotations (readOnlyHint, idempotentHint) by detailing the extraction process and output format.

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 only 3 sentences. It front-loads the main action and purpose, then provides behavioral details and use cases. 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?

For a tool with only 2 parameters and no output schema, the description covers the input, process, output format, and use cases comprehensively. It sets proper expectations for the generated file and its placement. No gaps are evident.

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

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

Schema coverage is 100% with both parameters (url and max_links) described. The description reiterates the parameter roles but does not add new semantic meaning beyond the schema. For example, the schema already notes defaults and max for max_links. Thus, the description adds marginal value, matching the baseline for high coverage.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL. It specifies the verb 'Generate', the resource 'llms.txt file', and lists concrete use cases (e.g., getting a client's site indexed, drafting for own project). It effectively distinguishes its purpose from sibling tools like ai_visibility_check.

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

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

The description provides explicit usage scenarios: getting a client's site indexed, drafting llms.txt for your own project, or auditing competitors. It does not mention when not to use this tool or cite alternatives, but the listed use cases give clear context for when it is appropriate.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds detail about the include_inactive parameter's effect and the exact fields returned, enhancing transparency beyond annotations.

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

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

Two concise sentences, front-loaded with purpose and return fields, followed by usage guidance. 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 (one optional boolean parameter, no output schema), the description fully covers purpose, return fields, usage, and parameter behavior.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add extra meaning about the parameter beyond what the schema's description 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 'List the caller's active subscriptions' and enumerates the returned fields (id, type, params, created_at, last_fired_at, fire_count), distinguishing it 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?

Explicitly tells when to use: 'review what you're monitoring before adding more or to find an id to cancel,' which implies alternatives (subscribe, unsubscribe) and provides clear context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds 'quick access' but does not disclose additional behavioral traits such as response or data limitations, offering minimal extra 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 a single, front-loaded sentence with no wasted words. It efficiently conveys the tool's core 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?

Despite schema examples and output schema, the description is minimal and does not explain defaults (e.g., national state), range syntax, or usage expectations, leaving some gaps for the agent.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description adds no new meaning beyond summarizing the tool's function, making it adequate but not enhanced.

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 US crop yields, production totals, and acreage by crop, state, and year, distinguishing it from sibling tools like nass_crop_progress (progress data) and nass_livestock (livestock data).

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

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

The description implies usage for 'quick access to major crop survey data' but does not explicitly state when to use this tool versus alternatives like nass_query for more general queries. No exclusions or context cues are provided.

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

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

Annotations already confirm read-only and non-destructive behavior. The description adds useful context about the data scope (weekly reports, condition ratings) beyond annotations, though no side effects or rate limits are disclosed.

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?

A single, front-loaded sentence with no unnecessary words. Every piece of information is meaningful and earns its place.

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

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

With a full input schema, comprehensive annotations, and an output schema present, the description adequately covers the tool's purpose, data types, and scope. No gaps remain for an agent to misunderstand.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add parameter details beyond what the schema already provides; it mentions 'by crop and state' but that is also in the 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 clearly states the tool retrieves 'weekly crop progress reports' with specific growth stages and condition ratings, distinguishing it from siblings like nass_crop_production and nass_prices.

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

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

No explicit when-to-use or when-not-to-use guidance is provided. While the description implies it is for progress data, it does not differentiate from other NASS tools or mention alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds no further behavioral context such as authentication requirements, rate limits, or potential side effects. No contradiction.

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

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

Two sentences, zero waste. First sentence immediately states core function. Well-structured 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?

With output schema present, description need not detail return values. It covers basic scope but could mention the required API key parameter or optional filters more explicitly. Still adequately 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 clear descriptions for each parameter. Tool description does not add additional meaning beyond what the schema provides. 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?

Clear verb 'Get' and resource 'livestock inventory, slaughter counts, production data'. Distinguishes from sibling tools like nass_crop_production, which focus on crops.

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

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

No explicit guidance on when to use this tool versus alternatives. Does not mention that crop-related data should use nass_crop_production or that nass_query might be for custom 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 declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds behavioral context about tracking trends and market movements, which is beyond the structured annotations.

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

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

Two sentences, front-loaded with the core action. Every word is purposeful; no fluff.

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

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

Given the output schema exists, the description is sufficient. It clearly states what data is retrieved and the available filters (commodity, state, year), meeting the needs for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents parameters well. The description does not add significant parameter-specific meaning beyond what the schema provides.

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

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

The description clearly states the verb 'Get' and the resource 'prices received by US farmers', specifying dimensions (commodity, state, year). It distinguishes from sibling tools like nass_crop_production and nass_livestock.

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

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

No explicit guidance on when to use this tool vs alternatives. The description lacks when-not or alternative recommendations, leaving the agent to infer usage from context.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that it returns production, yield, acreage, prices, and livestock data, which is useful context. However, it does not mention any potential limitations (e.g., data freshness, API key requirement already in schema) or side effects beyond what annotations cover.

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

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

Two sentences with clear front-loading of purpose and a concrete example. It is efficient and informative, though it could benefit from a brief usage guideline to improve structure.

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 10 parameters, output schema, and annotations, the description covers the basics but is incomplete in differentiating from sibling tools. It adequately describes the tool's function and return types, but lacks guidance on when to use this tool over alternatives like nass_crop_production.

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% parameter description coverage, so baseline is 3. The description provides an example (commodity='CORN', state_fips='06') that adds concrete usage context, but no additional semantics beyond what the schema already defines for each parameter.

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 verb 'Search' and resource 'USDA agricultural statistics by commodity, statistic, geography, and year'. It includes return data types (production, yield, etc.). However, it does not explicitly differentiate from more specific sibling tools like nass_crop_production or nass_prices, which could cause confusion about which tool to use for a narrower 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?

No guidance on when to use this general query tool versus the specialized siblings. The description lacks any conditions, prerequisites, or context for selection. An agent would have no basis to choose this over nass_crop_production for crop-specific data.

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 limit (5/day), free usage, no quota impact, and that team reads daily with roadmap impact. Annotations are all false, consistent with feedback being a non-destructive write.

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

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

Well-structured with front-loaded purpose, clear usage guidelines, and constraints. Every sentence adds value; no redundancy. Appropriate length for the complexity.

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

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

Complete for a feedback tool with no output schema. Covers action, types, rate limits, usage guidance, and behavioral traits. No additional information needed.

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

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

Schema has 100% coverage, baseline 3. Description adds extra semantics: explains type enum categories in context, warns not to paste prompts, and recommends specificity. Adds value beyond schema.

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

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

Description clearly states it sends feedback to Pipeworx team (bugs, missing features, praise). Distinguishes itself from sibling tools by being the only feedback tool. Specific verb 'Tell' + resource.

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

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

Explicitly states when to use: for bugs, missing tools, praise. Provides exclusions: don't paste end-user prompt. No alternative tool for feedback, so usage is singular.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotent=true. The description adds valuable context: data source ('CF analytics-engine'), privacy ('no PII'), caching behavior ('cached 5min-1h depending on window'), and output structure ('(pack, tool, count)'). This goes beyond annotations to inform the agent about timeliness and data origin.

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 yet comprehensive, front-loading the main action in the first sentence. It uses a bulleted list (in prose) to present use cases efficiently. Every sentence provides unique value without redundancy. Ideal length for an MCP 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?

The description explains what is returned (top tools, packs, volume), the data source, and caching. Although there is no output schema, the description gives enough detail for an agent to understand the response format. It could explicitly state the output is a JSON list or similar, but overall it is sufficiently complete for the tool's simplicity.

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

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

The input schema already has a well-described parameter with enum values. The description adds meaning by explaining the effect of window choice: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This contextualizes the parameter beyond the enum labels, improving decision-making for the agent.

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

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

The description clearly states what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window.' It specifies the unique value of showing 'what other AI agents are calling on Pipeworx right now,' distinguishing it from sibling tools that focus on individual queries or specific data sources.

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

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

The description provides explicit use cases: 'discovering what data sources are hot,' 'confirming a popular tool is the canonical choice,' and 'seeing whether your use case aligns with what most agents need.' It does not specify when not to use, but these clear scenarios guide appropriate invocation. No mention of alternatives, but siblings are unrelated.

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 and destructiveHint=false. The description adds rich behavioral context beyond annotations: two modes, partition check, similarity threshold, placeholder filtering, fill check, and trade suggestions. 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 somewhat long but well-structured with headings and all-caps keywords. It front-loads the requirement. While dense, each sentence provides necessary detail for a complex tool. Minor verbosity but earned.

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

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

Given no output schema, the description thoroughly explains the response fields: opportunities array, partition_check object, fill check details. It covers edge cases like placeholders_filtered, thin_legs, and realizable_edge_pp. Complete for a tool of this complexity.

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

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

Schema coverage is 100%, baseline 3. The description adds significant value: explains event slug formats, what topic means, and the behavior of each parameter (e.g., 'walks child markets', 'searches related events'). It also clarifies the semantics of no args failing.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between event mode (single-event) and topic mode (cross-event). The verb 'Find' and resource 'arbitrage opportunities' are specific, and it differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidelines: 'event (recommended for a specific market)' and 'topic (for cross-event scanning).' It states 'call with no args fails' and mentions alternative tool polymarket_fill_risk for custom sizing. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate read-only and idempotent behavior, but the description adds extensive behavioral details: three model families, output structure (by_segment, diagnostic fields), caching at KV level (1h keyed on knobs), and filter logic. 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 lengthy but well-organized into sections (model families, response structure, diagnostics). While dense, it efficiently conveys complex information without redundancy. Minor improvements could trim some details, but overall it's appropriately sized 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?

Given 9 parameters, no output schema, and high complexity, the description thoroughly documents output structure (by_segment, each opportunity's fields, fed_note, diagnostics) and behavior. It provides exhaustive detail for correct agent use, compensating fully for the missing output schema.

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

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

Schema coverage is 100%, but the description adds substantial meaning: explains default values, rationale (e.g., slippage_pp default 0.3 based on Polymarket spread), and nuanced behavior (e.g., min_partition_leg_kelly for partition arbs). Every parameter gets enhanced context.

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

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

The description clearly states the tool's purpose: scanning Polymarket markets to find opportunities where Pipeworx data disagrees with market price, specifically for daily betting decisions. It distinguishes itself from siblings like polymarket_arbitrage by focusing on Pipeworx edge detection.

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 specifies it's for 'what should I bet on today' and notes it avoids paging hundreds of markets, providing clear usage context. It also describes tradeable-edge knobs but doesn't explicitly state when not to use or contrast with siblings.

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

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

Annotations declare read-only, open-world, idempotent, non-destructive. The description adds behavioral details: response includes tracked, expired, snapshot_dates; trend and decay computed on absolute value; limitations like 60-day TTL and snapshot gaps. 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 somewhat long but front-loaded with purpose. Every sentence adds value, detailing response structure and limitations. Could be slightly trimmed but remains focused.

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

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

No output schema, so the description fully explains response fields (tracked, expired, snapshot_dates) with examples. Parameters are fully covered. Annotations present. Comprehensive for a telemetry tool.

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

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

Schema covers 100% of parameters with descriptions. The description adds defaults (14 days, '1wk'), clamping (2-30), and window options (24hr, 1wk, 1mo), supplementing 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 specifies 'edge persistence and decay telemetry', clearly stating it answers 'how long has this edge existed and is it shrinking?'. It distinguishes from sibling tool 'polymarket_edges' by focusing on time-series analysis rather than current edges.

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

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

The description explains when to use: to differentiate between a fresh wide edge and an old one. It provides context about why an old wide edge is different, but does not explicitly state when not to use or list alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details: walks the order book, returns verdicts (clean|degraded|cannot_fill), and warns about forced directional risk and thin legs. No contradiction with annotations.

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

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

The description is long but well-structured with sections and front-loaded purpose. Every sentence adds necessary detail given the tool's complexity. Could be slightly more concise, but the level of detail is justified.

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 the description lists return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, etc.) and explains their significance (thin_legs, forced_directional_risk). Complete enough for the agent to understand what the tool provides.

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 significant meaning: explains the difference between single-market and basket modes, default values for side and size_usd, and interpretation of size_usd (max spend on buys, target proceeds on sells). Adds context beyond schema descriptions.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishing between single-market and basket modes with specific parameters and return fields. It differentiates from sibling tools like 'polymarket_arbitrage' and 'polymarket_edges' by focusing on fill risk and capturability.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and warns about scenarios where partial basket fills convert an arb into a directional position, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds substantial value by detailing compatibility warnings, temporal alignment checks, skipped cross-type counters, and the real-world rarity of tradable spreads. 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 sections for purpose, modes, response, safety fields, and counters. It front-loads the core purpose. However, it is relatively long and includes some repetition (e.g., multiple mentions of compatibility warnings).

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 (cross-venue comparison, multiple edge cases), the description is remarkably complete. It explains the response format (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning cases, temporal alignment), and counters for dropped comparisons. Without an output schema, this level of detail is essential and well-provided.

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 all three parameters are described in the schema. The description adds meaning by explaining the two modes, listing the pre-mapped topic shortcuts, and noting that explicit parameters override topic-mapped sides. It does not repeat schema but 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 clearly states it computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It specifies two operational modes (topic shortcuts and explicit event tickers) and mentions the response structure. This distinguishes it from sibling tools like polymarket_arbitrage and others that focus on single-venue analysis.

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

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

The description explains when to use the tool (comparing venues) and includes important caveats: non-equivalent bet shapes, temporal misalignment, and semantic mismatch. It does not explicitly name alternative tools but provides clear context for when results may be invalid.

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 (read-only, idempotent, non-destructive), the description adds scoping context: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' This is valuable 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?

Three sentences, each serving a purpose: core action, usage motivation, and pairing with siblings. No wasted words.

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

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

For a simple retrieval tool with clear schema and annotations, the description fully covers purpose, usage context, scoping, and relationships with 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%, but description adds meaningful usage info: omitting key lists all keys, and provides examples of what keys store (ticker, address, notes).

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 'retrieve' and 'list', specifies the resource (saved values/keys), and clearly distinguishes from sibling tools 'remember' and 'forget'.

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

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

Provides clear context on when to use (look up stored context) and mentions pairing with remember/forget, but lacks explicit when-not-to-use guidance.

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

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

The description includes 'Set mark_read:true to flag returned events read', which implies a state mutation, contradicting the annotation 'readOnlyHint': true. This is a serious inconsistency that undermines 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 concise with four focused sentences. It front-loads the purpose and efficiently covers key behaviors, filters, and alternative access.

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

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

The description explains return fields (source, citation_uri, raw payload) and filter options. However, it lacks detail on ordering (assumes most recent) and does not address pagination beyond the 'limit' parameter.

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

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

The description adds meaning beyond the schema by explaining the mark_read side effect ('so the next call only shows newer ones'), providing an example for type ('sec_8k'), and clarifying that 'since' expects an ISO timestamp. Schema coverage is 100% but the description enriches all parameters.

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 'Pull fired events from your subscription feed' using a specific verb ('Pull') and resource ('fired events'). It distinguishes itself from siblings like 'list_subscriptions' and 'subscribe' by focusing on retrieving alerts rather than managing subscriptions.

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

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

The description provides guidance on filtering by type and since, and mentions polling works fine with an alternative REST endpoint. However, it does not explicitly compare to sibling tools like 'search_within' 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 readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds behavioral context: fan-out to multiple sources, return structure (changes[] grouped by source + count + URIs), GDELT→GNews fallback, and USPTO soft-fail.

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

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

The description is a single paragraph but packs essential information efficiently, front-loading example queries. No wasted words, though bullet points could improve scanability. Still, very concise for the complexity covered.

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

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

Despite lacking an output schema, the description fully explains the return format ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs') and all source behaviors. Complete for a complex multi-source tool.

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

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

Schema coverage is 100% so baseline 3, but the description adds value by explaining 'since' accepts ISO and relative formats with examples, and clarifies 'value' can be ticker or CIK. Adds 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?

The description clearly states the tool provides a change feed for a company in a recent time window, enumerating three data sources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishes from sibling tool 'entity_profile'.

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

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

Explicitly tells when to use this tool ('What's new with X', 'latest on Y', etc.) and when to use entity_profile instead. Provides detailed usage instructions for the 'since' parameter and fallback behavior for news sources.

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 idempotentHint (true) and destructiveHint (false). The description adds useful behavioral details: persistence differences between authenticated (permanent) and anonymous (24-hour) sessions, and scoping by identifier. 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 concise—three sentences that convey purpose, usage, and behavioral details. No superfluous words, and the key information is front-loaded.

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

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

Given no output schema, the description does not need to cover return values. It adequately covers storage scope, persistence, and pairing. Minor omissions (e.g., overwrite behavior) prevent a perfect score, but 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?

The input schema has 100% coverage with clear descriptions for key and value. The description does not add significant new semantics beyond the schema, such as format constraints or defaults. A score of 3 is appropriate as the schema carries the burden.

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

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

The description clearly defines the tool's purpose: to save data for reuse across sessions or conversations. It provides concrete examples of what to store (e.g., resolved ticker, user preference) and distinguishes it from sibling tools 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?

The description explicitly states when to use this tool ('when you discover something worth carrying forward') and explains its pairing with recall and forget. It also clarifies scoping and persistence, offering comprehensive usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: cascades through multiple lookup endpoints, auto-disambiguates for company, and replaces 2-3 manual steps. No contradictions.

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

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

The description is well-structured: starts with examples and purpose, then details supported types with return info. Every sentence adds value; no redundancy. Slightly longer but justified by the amount of useful information.

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

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

Without an output schema, the description fully compensates by explaining return values for both entity types, input formats, and internal behavior. It covers all aspects needed for an AI agent to use the tool correctly.

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

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

Schema coverage is 100%, baseline 3. The description significantly enhances parameter meaning by detailing return values for each type (taxonomy-specific fields like CIK, RxCUI) and clarifying input formats beyond the schema's brief descriptions.

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

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

The description uses specific verbs like 'resolve' and gives concrete examples ('What's the ticker for...'), clearly stating the tool maps names to official identifiers. It distinguishes from sibling tools by noting it replaces multiple manual lookups.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. While it doesn't explicitly say when not to use, the priority hint is sufficient and supported by examples of supported types.

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

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

The description discloses that the tool probes each entity with `ai_visibility_check`, ranks by score, and returns a ranked list with score, confidence, and signal density. It also explains that `workers-ai` is the free default model and that `_apiKey` is only required for `anthropic`. These details go beyond the annotations (which already indicate read-only, idempotent, non-destructive behavior) and add valuable behavioral context.

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

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

The description is two efficient sentences followed by a brief usage example. Every sentence adds value: it states the primary action, the mechanism, the use case, and the return structure. No redundant or wasteful text.

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 no output schema, the description adequately explains the return values (ranked list with score, confidence, signal density). It covers required parameters, default behavior, and the rationale for each parameter. For a tool with rich annotations and clear parameter schema coverage, this description is 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 tool description adds meaning by explaining that `workers-ai` is the free default, that `_apiKey` is conditional on including 'anthropic' in models, and that `context` disambiguates common names. It also clarifies that the first entity in the array is treated as the 'subject' for narrative purposes, which is not evident from the schema alone.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, ranks them by score, and surfaces most/least recognized. It distinguishes from sibling tools like `ai_visibility_check` (single entity) and `compare_entities` (generic comparison) by specifying the mechanism (probing with `ai_visibility_check`) and the output format (ranked list).

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

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

The description provides explicit context: 'Useful for competitive AI-marketing audits' and gives a concrete example question. It notes that the first entity is treated as the 'subject' for narrative. However, it does not explicitly state when not to use this tool versus alternatives like `ai_visibility_check` for single probes.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed will list timeouts, and the return structure. No contradiction with annotations.

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

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

The description is one dense paragraph but each sentence serves a purpose. It could be slightly more structured (e.g., bullet points) for easier parsing, but it's not overly verbose and all information is relevant.

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

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

Given the tool's complexity (multi-source composite check), the description covers all major aspects: data sources, parameters, return structure, partial failure behavior, ecosystem limitations, and timeouts. No output schema, but the description explains the return fields clearly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value beyond schema: it explains scoped packages are accepted, and that version defaults to latest when omitted. This provides useful context for parameter usage.

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

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

The description clearly states it's a composite check for deciding whether to add an npm package, fanning out across deps.dev and bundlephobia. It specifies inputs (npm package name/version) and return structure. The purpose is distinct from siblings, and ecosystem limitations are explicitly noted.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small' or 'what does adding lodash cost me' It also tells when not to use: for PyPI/Maven/Cargo/Go, use deps.dev:version directly. Provides clear alternatives.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description discloses technical details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' This gives the agent important behavioral knowledge missing from structured fields.

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

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

The description is a tight 4-sentence paragraph with no wasted words. It front-loads the core purpose, then adds usage guidance, pairing, and technical detail. Every sentence earns its place.

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

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

Given no output schema, the description explains the return format (passages with offsets and scores) and caps. It covers the tool's inner mechanics (embedding model, windowing, truncation) and workflow pairing. This is highly complete for a 3-param tool.

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

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

Schema coverage is 100%, so the schema already describes all parameters. The description adds minimal value for parameters (e.g., 'Pass the text you already pulled' for text, and 'natural-language query' for query) but does not provide additional semantics beyond what is in 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 'Semantic search INSIDE a fetched record' and specifies the inputs (text and query) and outputs (top-N passages with offsets and scores). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded, making the tool's role in a workflow explicit.

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 the tool: 'when the record is too big to cram into the prompt'. It also provides an alternative workflow by pairing with ask_pipeworx_grounded, guiding the agent on how to combine tools effectively.

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

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

The description goes far beyond annotations by detailing subscription type parameters with examples, delivery channel constraints (SMS verification, 10/day cap, webhook auto-disable after 10 failures, one-time signing secret), and prerequisite requirements. Annotations only indicate non-readonly, open-world, idempotent, and non-destructive traits, which the description supports without contradiction.

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

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

The description is a single dense paragraph that front-loads the main purpose and then covers types and delivery channels. While effective, it could benefit from bullet points or clearer separation for readability. It earns its sentences but is slightly dense.

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

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

Given the complexity (3 parameters with nested objects, 5 types, multiple deliveries), the description covers the core functionality, prerequisites, type examples, delivery options, and return value. It does not detail error handling or idempotency behavior, but these are partially covered by annotations and schema validation.

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

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

With 100% schema description coverage, the description still adds value by providing type-specific parameter examples (e.g., 'sec_8k: {ticker:"AAPL", items?:["5.02","1.01"]}'), explaining delivery options in detail, and clarifying constraints like phone verification. This enhances understanding beyond the raw 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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. The verb 'subscribe' combined with the resource 'Alerts' and the mention of specific subscription types distinguishes it from siblings like 'list_subscriptions' and 'unsubscribe'.

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

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

The description provides clear context: requires a Pipeworx OAuth account, mentions that anonymous/BYO cannot persist subscriptions, and details supported types and delivery channels. However, it does not explicitly state when not to use this tool or provide direct alternatives, though sibling tools are available for context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as safe. The description adds context about being a meta-tool for onboarding, clarifying that it returns structured question-tool mappings. No contradictions.

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

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

Description is thorough and well-organized, starting with purpose, then examples, then argument guidance. Each sentence adds value, though slightly verbose; could be tightened without losing information.

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

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

Given no output schema, the description adequately explains return type (category-bucketed example questions with exact tool shapes). It also provides context for use with other meta-tools. Minor gap: does not specify if results are paginated or limited.

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 one optional parameter. Description explains that omitting topic gives a cross-category spread, while passing a topic (enumerated: finance, pharma, etc.) focuses the results, adding value beyond the schema 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?

Clearly states the tool is the onboarding entry point that returns category-bucketed example questions. Verb 'suggest' matches title, and it distinguishes itself from siblings by being the first-use tool for learning about Pipeworx capabilities.

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

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

Explicitly says 'Use this FIRST' when unsure what Pipeworx can do, and provides guidance on when to omit or specify the topic argument. Names alternative meta-tools (ask_pipeworx, entity_profile, etc.) as learning resources.

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

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

Beyond annotations (idempotentHint, destructiveHint), the description adds important behavioral details such as ownership enforcement, deactivation instead of deletion, and historical event availability.

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 (two sentences, 22 words) and front-loaded with the main action, with every sentence providing 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?

For a simple tool with one parameter and no output schema, the description adequately covers the action, side effects, and constraints, making it 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 a clear description in the schema. The description does not add additional meaning beyond the schema, meeting the baseline.

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

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

The description clearly states the action 'Cancel a subscription by id' and differentiates from siblings like subscribe and list_subscriptions by mentioning ownership enforcement and soft-delete behavior.

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

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

The description implies usage context by stating ownership enforcement, but it does not explicitly specify when to use this tool versus alternatives or when not to use it.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds context about the return format (verdict, structured form, actual value with citation, percent delta) and notes that it replaces 4-6 sequential calls, which provides behavioral insight beyond annotations.

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

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

The description is concise, front-loading key use-case phrases and then providing scope, output, and efficiency benefits. Every sentence contributes essential information without redundancy.

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

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

Given the single parameter and no output schema, the description adequately covers the tool's input, output (verdict types, structured data, citation), limitations (company-financial claims for public US companies), and operational context (replaces multiple calls). It is complete for its 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% with a description for the 'claim' parameter. The tool's description adds value by providing natural-language examples and explaining the type of claims accepted (e.g., revenue, net income), which enhances the schema's meaning.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, specifically for company-financial claims. It provides distinct use-case examples and distinguishes itself from sibling tools by explicitly targeting fact-checking tasks.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and defines the scope (company-financial claims for public US companies). It does not provide explicit when-not-to-use scenarios, but the scope is clear enough for appropriate selection.

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