Data360

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

Annotations already convey read-only, idempotent, and non-destructive behavior. The description adds valuable context: the default model is free, Anthropic requires the user's own key and direct payment, and the return structure includes per-model scores, confidence, signals, and raw responses. 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 four sentences, each serving a purpose: (1) core function, (2) model and key details, (3) return structure, (4) use cases. No fluff or redundancy.

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

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

Given the absence of an output schema, the description adequately covers the return format (per-model object with score, confidence, signals, raw_response, plus combined view). It explains the tool's purpose, parameters, and typical use cases. However, it does not elaborate on what 'signals' or 'confidence' mean, leaving a minor gap.

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

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

Schema description coverage is 100%, but the description adds meaning beyond the schema by explaining the default model behavior and the optional nature of the Anthropic key. It also clarifies that 'context' helps disambiguate common names, which the schema alone does not convey.

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

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

The description uses specific verbs ('probe', 'score') and clearly identifies the resource (LLM visibility for a business/brand/product/topic). It distinguishes itself from sibling tools like 'scan_competitor_ai_presence' by focusing on probing multiple LLMs and returning a visibility score.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains model selection (default Workers AI, optional Anthropic with API key). However, it does not explicitly describe when to avoid using this tool or contrast it directly with 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 cover read-only/idempotent safety; description adds that it returns structured answers with pipeworx:// citation URIs, routes across 5,529 tools, and makes 'one fast call'. No contradiction, but doesn't mention edge cases like rate limits or error handling.

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

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

Long but well-structured: front-loaded directive, examples, alternatives, and exceptions. Some repetition ('START HERE', 'works on every tier') could be trimmed, but every section adds operational value for a default meta-tool.

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

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

No output schema, so description compensates by explaining return format (structured answer with stable citation URIs) and escalation paths to siblings. For a complex routing tool, this is complete guidance.

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

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

Schema already covers all parameters with aliases and examples. Description adds illustrative questions but no extra semantic detail beyond what the schema provides. Baseline 3 is appropriate since schema does the heavy lifting.

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

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

The description clearly states it answers factual questions by routing to the right tool, distinguishing itself from web search and siblings like ask_pipeworx_grounded and deep_research. Specific verb 'ask' plus resource 'Pipeworx' with explicit scope of data domains.

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

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

Explicitly instructs to prefer this over web search, gives trigger phrases ('what is', 'look up', etc.), and names when to use alternatives (ask_pipeworx_grounded for verbatim evidence, deep_research for broad multi-part questions). This is textbook when/when-not guidance.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description adds critical behavioral context: it is an experimental router with candidate routing improvements that are enabled live when under test. It transparently discloses the current state (no active candidate, matches ask_pipeworx) and its role in evaluation. This is especially valuable given the tool's dynamic behavior.

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

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

The description is four sentences long and front-loaded with the core purpose first. Every sentence adds value: purpose, current state, usage guidance, and reassurance of functionality. 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?

With no output schema, the description compensates by stating 'same response shape' as ask_pipeworx, which is adequate. It also covers current availability, behavior differences, and usage context, making it a complete profile for an experimental variant.

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

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

The input schema already documents all six parameters with a 100% coverage, including aliases for the required 'question' field. The description adds no new parameter-level semantics beyond stating 'same arguments' as ask_pipeworx. Thus the schema carries the burden, matching 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 this is a beta version of ask_pipeworx: an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by highlighting its experimental routing improvements and current exact-match status.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing,' providing a clear usage scenario. It also notes that results are compared against the stable router, implying when not to use it (when you need stable behavior). The disclaimer that it 'falls back to nothing' assures it is fully functional.

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 the description adds substantial context: extraction uses ONLY tool results, returns evidence/refusal reasons, and costs an extra LLM call. No contradiction with annotations.

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

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

Front-loaded with a clear purpose statement, then process, return shape, and usage guidance. Every sentence carries essential information without 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?

No output schema exists, so the description fully covers return values, refusal cases, use cases, and operational cost. Complete for a complex tool.

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

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

Schema coverage is 100%, including the question parameter with aliases. The description does not add parameter-specific details beyond implying the tool accepts a natural language question, so baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, with a specific verb ('ask') and resource. It differentiates from sibling ask_pipeworx by outlining the grounded extraction process and explicit refusal behavior.

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

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

Explicitly states when to use (quoted, cited, acted on, high-stakes) and when not to (casual lookups), naming the alternative (ask_pipeworx) and noting the extra LLM call cost.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds extensive detail beyond annotations: low-confidence handling, closed market behavior, wide-spread warnings, cancellation rule parsing, news fallback mechanisms, and response shape documentation. 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 very long and detailed, which is valuable but not concise. It is front-loaded with the main purpose and uses section headers, but contains some redundancy (e.g., cancellation rules mentioned twice). An agent reading it might take longer to parse than necessary.

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

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

Given the tool has 3 parameters, no output schema, and high complexity, the description is remarkably complete. It covers edge cases (low confidence, closed markets, wide spreads, cancellation rules), explains all major response fields, and describes fallback behavior for news sources. An agent has sufficient context to use the tool effectively.

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

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

The input schema covers all 3 parameters with 100% description coverage. The description adds value by explaining that 'market' can be a slug, URL, or question text; what 'depth' values do; and when to use 'include_raw' (false recommended for normal use, true for specific needs). This goes beyond 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 specifies the tool researches Polymarket bets by fetching Pipeworx data. It gives clear use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and distinguishes itself from sibling tools like polymarket_arbitrage or polymarket_edges by focusing on research and evidence gathering.

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 the tool for specific question types and provides classifiers and fan-out examples. However, it does not explicitly mention when not to use it or directly compare to alternatives, though the purpose is clear enough for an agent to infer appropriate contexts.

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

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

Beyond the annotations (readOnlyHint, etc.), the description discloses detailed behavioral traits: it pulls data from specific sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handles off-calendar fiscal years correctly, returns paired data with citation URIs, and sorts results by primary metric. This adds substantial context not present in 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 yet comprehensive, front-loaded with user-facing examples. Every sentence serves a purpose, from usage examples to data source details to result format. No redundant or superfluous information.

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

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

Despite no output schema, the description covers all critical aspects: input parameters, data sources, result structure (paired data + citation URIs), and behavioral specifics (sorting, fiscal year handling). It is fully complete for an agent to correctly select and invoke the tool.

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

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

Schema coverage is 100%, but the description adds significant value by explaining what each 'type' returns (e.g., 'company' pulls revenue, net income, cash, long-term debt) and how 'values' should be formatted (tickers/CIKs for companies, drug names). This goes well 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 starts with multiple user query examples ('Compare X and Y', 'X vs Y', etc.) and clearly states the tool's function: side-by-side comparison of 2–5 companies or drugs in a single parallel call. It distinguishes itself from sequential single-pack lookups, making the purpose highly specific and 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 explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear guidance on when to use this tool over an alternative. It also notes that it replaces 8–15 sequential lookups, further reinforcing its preferred use case.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral details: returns SDMX-style records with specific attributes and explains that omitting TIME_PERIOD returns the full series. No contradictions.

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

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

Three sentences with no wasted words. First sentence states purpose, second explains parameters, third covers output and optional behavior. Front-loaded 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?

Covers purpose, parameter roles, output structure, and cross-reference to sibling. No output schema is present, but the description explains return fields. Could mention pagination (top/skip) but those are in schema. Overall adequate given 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%, but the description adds rich meaning: explains DATABASE_ID selects source, INDICATOR is a code from a sibling tool, REF_AREA is ISO3, and TIME_PERIOD is optional. Examples illustrate usage, fully compensating for schema's 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 'Fetch observations for one Data360 series', specifying the verb and resource. It distinguishes from sibling tools like data360_list_databases and data360_search_indicators by focusing on fetching observations for a single series.

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 parameter guidance, including cross-referencing data360_search_indicators for INDICATOR codes and explaining optional TIME_PERIOD. However, it does not explicitly state when not to use this tool or alternative tools for multiple series.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds context about return format (DATABASE_ID, full name, indicator count) and default pagination (top=200). 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?

Two sentences: first covers purpose and examples, second covers return format and downstream usage. No unnecessary words, information is front-loaded and structured efficiently.

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 (listing databases), no output schema is needed. The description fully explains what the tool does, what it returns, and how the output is used, 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 description for the single 'top' parameter. The description does not add any extra semantic information about the parameter 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?

Clearly states it lists source databases aggregated by World Bank Data360, provides concrete examples of database IDs (WB_WDI, IMF_BOP) and explains what is returned (DATABASE_ID, full name, indicator count). Distinguishes from siblings by specifying that the returned DATABASE_ID can be used to scope other tools.

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

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

Explicitly states that the tool provides DATABASE_IDs for use with data360_search_indicators and data360_get_data, guiding the agent on when to use it. Does not explicitly state when not to use it or mention alternatives, but the context is clear.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds value by detailing indexed sources and returned fields (indicator codes, names, database info, units, definitions). 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?

Two sentences, front-loaded with core functionality. Every sentence is informative with no redundancy. Ideal conciseness.

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

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

No output schema, but description lists all returned fields (indicator codes, names, database info, units, definitions). All parameters are documented in schema; description adds inter-tool guidance. Complete for a search tool.

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

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

Schema covers all 4 parameters with descriptions (100% coverage). Description adds minor context by relating parameters to usage (e.g., 'use as INDICATOR in data360_get_data', 'restrict to one database'). Baseline of 3 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?

Clearly states the tool performs full-text search across all Data360 indicators, listing specific data sources (WDI/IMF/WHO/ILO/education). It distinguishes itself from sibling tools like data360_get_data and data360_list_databases by specifying it returns indicator codes for use in data360_get_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?

Implies usage: search indicators before getting data with data360_get_data. Mentions optional database_id restriction. Lacks explicit when-not-to-use or alternatives, but context from sibling tools makes it clear.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior, and the description adds rich behavioral detail: account sign-in needed, paid tier for 'thorough', parallel decomposition across 5,529 tools, findings packet structure with evidence/confidence/source/fetched_at, explicit gaps[] with never-invented policy, contradictions[] for standard/thorough, semantic excerpting, and 15-90s latency. This far exceeds what annotations alone convey and sets accurate expectations for the agent.

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

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

The description is long but each sentence contributes substantive guidance: account prerequisites, core behavior, usage boundaries, depth semantics, citation guarantees, gap/contradiction handling, excerpting rationale, and latency. It front-loads the critical account requirement and is organized logically, though a more bulleted structure could improve scannability.

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

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

Given the tool's complexity, lack of output schema, and two parameters, the description is exceptionally complete. It covers prerequisites, alternatives, expected output format, error/limitation handling (gaps[]), citation resolvability, contradictions, semantic excerpting, and timing. An agent has enough detail to invoke the tool correctly and interpret results without additional structures.

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 fully documents both parameters with 100% coverage, including enum meanings for depth and a clear question description. The description adds value by explaining behavioral consequences of depth choices ('standard re-angles unanswered gaps', 'thorough additionally chases leads') and clarifying that broad multi-part questions are appropriate, which enhances the agent's ability to set parameters correctly.

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

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

The description clearly identifies the tool as 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call' and explicitly contrasts it with open-web search. It also distinguishes from sibling tools by naming ask_pipeworx for single lookups and current-news topics, making its purpose unique and specific.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' with concrete examples, and clearly states alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also covers account requirements and fallback behavior for unsigned users, going beyond mere context into actionable selection criteria.

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

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

Annotations indicate readOnly, idempotent, non-destructive. Description adds that results include full schemas with examples and are ready to call directly, plus notes query alias flexibility. 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 well-structured: purpose first, then usage scenarios, then return value, then directive. Every sentence earns its place with no redundancy.

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

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

For a discovery tool with one required param and no output schema, the description fully covers purpose, usage, return format, and when to invoke. No major gaps.

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

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

Schema coverage is 100%, so baseline is 3. Description enhances by listing aliases (task, q, search, description) and providing natural language examples, adding clarity 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 explicitly states 'Find tools by describing the data or task' and provides specific domain examples. It distinguishes this meta-tool from siblings by directing to call it first when exploring available tools.

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

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

Clearly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and instructs to 'Call this FIRST' to see options. Lacks explicit when-not or alternative tools, but context is sufficient.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds valuable behavioral context beyond annotations: it fans out across multiple sources in parallel, returns specific data fields, and mentions that the USPTO patents part may soft-fail until reactivated. This provides the agent with deeper understanding of the tool's operation and limitations.

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

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

The description is informative and well-structured, starting with example queries that help an AI agent recognize user intent. However, it is somewhat lengthy and could be slightly trimmed without losing essential information, though every sentence adds value.

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

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

Given no output schema, the description does a good job explaining the return data (cik, filings with URIs, fundamentals, patents, news, LEI) and constraints (US only, name not supported, patent soft-fail). It covers the tool's complexity and limitations, though it lacks explicit return format details for fundamentals.

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 'type' and 'value'. The description reiterates that 'value' accepts ticker or CIK and that names are not supported, but adds no new semantic information beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states that the tool provides a comprehensive, cross-source profile of a US public company in one call. It distinguishes itself from siblings like 'resolve_entity' by noting that names are not supported, and it explicitly prefers over chaining multiple individual 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 gives explicit usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies that names are not supported and suggests using 'resolve_entity' first, providing clear when-to-use and when-not-to-use instructions.

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

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

Annotations already provide destructiveHint=true and readOnlyHint=false. The description adds useful behavioral context about why to delete (stale context, sensitive data), 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?

The description is two sentences with no wasted words. It front-loads the action and purpose, then provides usage guidelines.

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 delete-by-key tool with no output schema, the description covers the action, when to use, and pairing with siblings. It is complete for the level of 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 clear parameter description 'Memory key to delete'. The description adds no new semantic information beyond the schema, so baseline 3 is appropriate.

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

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

The description uses the strong verb 'Delete' and specifies the resource 'previously stored memory by key'. It also distinguishes from siblings by stating 'Pair with remember and recall.'

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

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

The description explicitly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions 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?

Annotations (readOnlyHint, idempotentHint, destructiveHint false) already ensure safe, read-only behavior. The description adds meaningful behavioral detail: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. No contradictions.

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

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

Three concise sentences plus a bullet list of use cases. Every sentence adds unique value — purpose, process, output format, and usage. No redundancy or fluff.

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

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

For a simple, focused tool with 2 parameters and no output schema, the description covers all necessary aspects: input, behavior, output, and use cases. No gaps in understanding what the tool does and how to use it.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (url, max_links). The description does not add extra context beyond the schema (e.g., URL format, default behavior). Baseline 3 is appropriate.

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

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

The description starts with 'Generate a production-ready llms.txt file for any URL' — a specific verb and resource. It explicitly distinguishes from sibling tools like ai_visibility_check and scan_competitor_ai_presence by listing concrete use cases (client site indexing, drafting, competitor auditing).

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 enumerates three specific use cases (client site indexing, own project, competitor auditing), providing clear context for when to use. It does not explicitly state when not to use or name alternatives, but the use case guidance is sufficient for selection.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, etc. The description adds value by specifying that only active subscriptions are returned by default and listing the returned fields, without contradicting any 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 with zero wasted words: first delivers purpose and output, second provides usage guidance. Efficient and 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?

For a simple list tool with one optional parameter and no output schema, the description fully covers purpose, usage, return fields, and parameter effect. No gaps.

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

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

Schema coverage is 100%, so the schema fully documents the parameter. The description adds context about the default (active only) but does not significantly enhance meaning 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?

The description clearly states the verb 'list' and resource 'subscriptions', specifying 'caller's active' scope. It distinguishes from sibling tools like subscribe/unsubscribe by focusing on reading existing 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 explicitly says 'use this to review what you're monitoring before adding more or to find an id to cancel', providing clear context for when to invoke. However, it does not explicitly state when not to use or name alternatives directly.

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

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

Discloses rate limits ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and the claim_token workflow ('Filing without an account returns a claim_token; pass it back later...'). Since annotations provide only false hints, this context is valuable.

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?

First sentence immediately states purpose; subsequent sentences deliver necessary operational and boundary information. Some redundancy (e.g., claim_token details repeated from schema) makes it slightly longer than minimal, but no wasted sentences.

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

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

Given no output schema, the description explains the return mechanism (claim_token) and expected behavior. It covers scoping, rate limits, and allowed content. It doesn't describe error responses, but for a feedback tool this is acceptable.

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

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

Schema describes all four parameters with 100% coverage, giving a baseline of 3. The description adds workflow context for claim_token (returns token on anonymous filing, later pass for status) and reiterates use-case mapping, elevating it marginally 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 a clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes from siblings by specifying it's for feedback on Pipeworx tools, not for data queries or research like sibling tools.

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

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

Provides explicit triggers: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also explicitly states exclusions: 'ONLY for tools served by this Pipeworx connection... file it with that server instead.'

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds valuable context: self-aggregating from CF analytics-engine, no PII, cached 5min-1h per window. 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 concise (three sentences plus a list of use cases) and front-loads the core functionality. Every sentence adds value, 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 low complexity (1 optional param, no output schema needed), the description covers purpose, usage, and behavioral details completely. No gaps remain for an agent to misuse the tool.

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

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

Only one parameter (window) with enum, and schema coverage is 100%. Description adds meaningful guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose the appropriate value.

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

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

Description clearly states what the tool does: returns top tools, top packs, and total call volume over a recent window. Distinguishes from siblings like ask_pipeworx or discover_tools by focusing on trending data derived from call volume.

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?

Description provides three specific use cases (discovering hot data sources, confirming canonical tool, aligning use case) which guide the agent on when to invoke. However, it does not explicitly exclude scenarios or compare to sibling tools.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: fill check against live CLOB depth, semantic anchor with Jaccard similarity threshold, partition filter with placeholder fraction, and detailed response 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 lengthy but well-structured with paragraphs and bolded key terms. Every sentence adds value; however, slight redundancy in explaining the same concepts (e.g., partition_check definition) could be trimmed. Still, it remains clear and informative.

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

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

Given the tool's complexity (multiple modes, semantic filtering, fill check) and no output schema, the description fully explains the response structure (opportunities[] with gap_pp, suggested_trade, etc.) and partition_check details. It covers all necessary aspects for correct invocation and interpretation.

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%, but the description adds meaning beyond parameter names: explains what an event slug is with examples ('fed-decision-may-2026'), describes topic as a seed question, and clarifies full Polymarket URLs are accepted. The description fully compensates for any schema limitations.

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 using monotonicity violations and partition-sum checks. It distinguishes three modes: trending scan (no args), event mode (specific slug), and topic mode (cross-event). It also differentiates from sibling polymarket_fill_risk by mentioning its use for custom sizing.

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

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

Explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also warns not to trade when realizable_edge_pp ≤ 0 and refers to polymarket_fill_risk for custom sizing.

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

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

The description aligns with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false). It goes beyond by detailing model families, caching (1h KV-level), diagnostics, and caveats like Fed bets exclusion and 24h-move warnings. 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 verbose (multiple paragraphs) but structured logically: purpose, model families, knobs, response format. Some redundancy exists (parameter names repeated). Its length is justified by complexity, but conciseness could be improved.

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 comprehensive annotations, the description thoroughly covers behavior, segments, diagnostics, caching, and edge cases. It effectively compensates for the missing output schema by explaining the response structure.

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

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

Schema coverage is 100%, and the description adds significant value by explaining rationale, defaults, and usage tips for each parameter (e.g., slippage_pp: 'Polymarket has zero trading fees… 20-50bp per trade'). This exceeds the baseline 3.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb (Scan), resource (Polymarket markets), and unique value (disagreement with Pipeworx). This differentiates it from siblings like polymarket_arbitrage.

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

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

The description provides clear usage context: 'Built for "what should I bet on today"' and 'agents discover opportunities without paging hundreds of markets.' It explains adjustable knobs like min_liquidity and max_spread_pp, though it lacks explicit exclusions or direct sibling differentiation.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are already given, but the description adds extensive behavioral context: reads from daily snapshots, TTL of 60 days, decay computation using daily closes, snapshot gaps meaning no scan, and detailed response structure. 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 long but well-structured, starting with a clear question, then parameters, then response sections. Every sentence adds value, though it could be slightly more concise.

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

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

With no output schema, the description thoroughly explains all return fields (tracked, expired, snapshot_dates) and covers limits. It is complete for a telemetry tool with two optional parameters.

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

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

Schema coverage is 100%, and the description adds default values and clarifies the meaning of 'window' as a snapshot family. It also explains the 'days' parameter's bounds. This adds some value beyond the schema, but not extensively.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific query about edge duration and shrinkage, distinguishing it from sibling tools like polymarket_edges and polymarket_arbitrage.

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

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

The description explains when to use the tool (to answer 'how long has this edge existed and is it shrinking?') and implies when not to (e.g., a 3-week-old wide edge is different). It does not explicitly name alternative tools, but context from sibling names makes it clear.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds detailed behavioral context: walks the order book ladder, returns verdicts (clean|degraded|cannot_fill), explains basket mechanics (thin_legs, forced_directional_risk), and warns about dominant loss mode. 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 relatively long but well-structured with clear sections for single-market and basket modes. It is front-loaded with the overall purpose, and every sentence contributes useful information. Could be slightly more concise without losing details.

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

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

Given the tool's complexity (two modes, 4 parameters, no output schema), the description is remarkably complete. It explains return values (top_of_book, vwap_fill_price, slippage_pp, etc.), the verdict system, basket-specific risks (thin_legs, forced_directional_risk), and provides enough context for an AI agent to use the tool correctly.

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

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

Schema coverage is 100%, but description adds significant value: explains side auto-detection for basket mode, clarifies size_usd interpretation (max spend on buys, target proceeds on sells, basket settlement notional), and provides constraints (clamp 10–1,000,000). These details go well 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 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes with specific return values. It differentiates itself from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use this tool.

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

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

Explicitly states required parameters ('REQUIRES one of market or event'), provides defaults for side and size_usd, and gives clear when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also warns about partial basket fills converting arb into unhedged directional position.

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

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

Adds significant behavioral context beyond annotations: describes compatibility_warning scenarios, temporal alignment checks, skipped cross type/subtype counters, and the limitation that pre-mapped topics are often not tradeable. This fully informs the agent of edge cases and data quality signals.

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 dense but well-structured: purpose, modes, response fields, safety fields, and caveats. Every sentence adds value, though it could be slightly more concise without losing information.

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

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

Given the complexity of cross-venue spread computation, no output schema, and 3 optional parameters, the description explains return fields (leg-by-leg prices, top_spreads), safety fields (compatibility_warning, temporal_alignment, skipped counters), and edge cases. It is comprehensive for a read-only query tool.

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

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

Schema coverage is 100% (baseline 3). Description adds value by enumerating the 10 topic shortcuts, providing explicit ticker examples, and explaining how parameters override topic mappings. Adds context for how parameters affect 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?

Clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. Distinguishes two modes (topic shortcuts and explicit tickers) and differentiates from siblings like polymarket_arbitrage by its cross-venue focus.

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 explains when to use topic vs explicit modes and warns that most pre-mapped topics return compatibility warnings. Provides guidance on interpreting spread validity (temporal alignment, bet shape equivalence). Lacks explicit comparison to sibling tools but context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint; description adds scoping and pairing info but no additional behavioral warnings beyond the annotations.

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

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

Three sentences, each purposeful: core function, usage context, scoping/pairing. 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?

No output schema; description mentions retrieving a value but does not specify return format or type, leaving some ambiguity for a simple key-value 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 parameter info; description repeats the same information about omitting key to list all keys, adding no new semantic detail.

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 retrieves a value by key or lists all keys if key is omitted, distinguishing it 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 usage context like looking up stored context (ticker, address, research notes) and scoping to user identifier, but does not explicitly state conditions when not to use.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details beyond annotations: it explains that mark_read:true modifies state (flags events as read), which is not obvious from 'idempotentHint=true'. It also describes return fields (source, citation_uri, raw event payload) and confirms poll suitability. 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 concise (4 sentences) and well-structured. The first sentence states the core purpose. Each subsequent sentence adds a distinct detail (return fields, filters, side effect, alternative access). No unnecessary words or redundancy.

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

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

Given the tool has 5 parameters and no output schema, the description covers key aspects: what is returned, filtering, state-changing behavior (mark_read), polling suitability, and an alternative endpoint. This is sufficient for an agent to understand and correctly invoke the tool without guessing.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by providing examples ('e.g. sec_8k' for type) and clarifying the effect of mark_read on subsequent calls. It does not repeat schema details but enriches the understanding of 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 the tool's purpose: 'Pull fired events from your subscription feed. Returns the most recent alerts...' It specifies the verb 'pull', the resource 'events from your subscription feed', and the action 'Returns the most recent alerts'. No sibling tools appear to have overlapping functionality, so differentiation is inherent.

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 when to use this tool, including filtering options ('Filter by type... and/or since'), a side-effect parameter ('Set mark_read:true to flag returned events read so the next call only shows newer ones'), and an alternative access method ('the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards'). It does not explicitly state when not to use it, but the context is clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description supplements with behavioral details: parallel fan-out to multiple sources, fallback logic, and soft-fail condition. 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 a single paragraph that efficiently front-loads query examples and core functionality. While it is somewhat long, every sentence serves a purpose and no information is redundant.

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

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

Despite no output schema, the description explains the return format (changes[] grouped by source, total_changes count, citation URIs). It covers multiple sources, fallback logic, parameter formats, and comparison with sibling tool, making it fully complete for the tool's complexity.

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

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

Schema description coverage is 100%. Description adds value by explaining that 'since' accepts ISO dates or relative shorthand (e.g., '7d', '30d'), that 'value' accepts ticker or zero-padded CIK, and that 'type' currently only supports 'company'.

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 provides a change feed for a company over a time window, listing specific sources (SEC EDGAR, GDELT→GNews, USPTO). It distinguishes from sibling 'entity_profile' by noting that tool is for static profiles.

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

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

Explicitly provides when-to-use guidance with example queries (e.g., "What's new with X"). It tells the agent to use 'entity_profile' instead for static data, and explains fallback behavior for GDELT→GNews and soft-fail for USPTO.

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 persistence behavior: 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' Annotations already indicate non-destructive and idempotent, but description adds valuable context without contradiction.

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

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

Four sentences, each adding distinct value: purpose, usage, scoping/persistence, and sibling pairing. No wasted words.

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

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

No output schema, but for a simple write operation, the description sufficiently covers behavior and retention. Minor gap: no explicit mention of return value.

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

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

Schema coverage is 100% with clear parameter descriptions. The tool description adds no extra parameter details, but baseline 3 is appropriate as schema does the heavy lifting.

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

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

Description clearly states the tool saves data for later reuse, specifying 'key-value pair scoped by your identifier.' It distinguishes from sibling tools recall and forget, which are mentioned.

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

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

Explicit guidance on when to use: 'when you discover something worth carrying forward.' Mentions pairing with recall and forget, but no direct exclusion of 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), the description adds rich behavioral details: identifiers are 'labelled with the source that established it', unresolved IDs are 'stated explicitly under `unresolved` rather than omitted', LEI/FIGI enrichment 'degrades gracefully' when GLEIF or OpenFIGI is unavailable, and each call cascades through internal endpoints. These traits are not derivable from annotations and significantly aid the agent's expectations.

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

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

The description is long but information-dense. It front-loads example queries for immediate recognition, then covers supported types, behavior, and error handling. Every sentence contributes value, though the structure could be improved with bullet points for readability. It is 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?

With no output schema, the description carries the burden of explaining return behavior. It covers source labels, unresolved field handling, graceful degradation, and the types of identifiers returned for both company and drug types. It does not provide a full output schema or exhaustive field list, but given the tool's scope, it is sufficiently complete for an agent to select and invoke it correctly.

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

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

Schema coverage is 100% and both parameters have clear descriptions. The description further elaborates on the 'type' parameter by detailing what 'company' and 'drug' entail (e.g., cross-source identity spine, RxNorm citation) and provides concrete examples for 'value' (AAPL, 0000320193). This adds contextual meaning beyond the schema's simple enum and string 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: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It includes specific query examples ('What's the ticker for…', 'find the CIK for…') and explicitly differentiates from sibling tools by framing it as the go-to when you have a name but need an ID, unlike entity_profile or compare_entities.

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

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

The description gives a strong usage directive: 'Use FIRST whenever you have a name but need an ID.' It also mentions that using resolve_entity replaces 2-3 manual lookups, implying efficiency. However, it does not explicitly state when NOT to use it or name alternative tools (e.g., entity_profile for existing IDs), so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds that the tool probes each entity with 'ai_visibility_check', ranks by score, and returns a ranked list with score, confidence, and signal density. This complements the annotations without contradiction.

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

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

The description is three sentences with no filler. It front-loads the core action ('Compare AI visibility across multiple entities'), includes a concrete use case, and efficiently covers output format. Every sentence adds value.

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

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

With no output schema, the description fully compensates by stating the return format (ranked list with score, confidence, signal density). It covers purpose, input parameters, and usage context thoroughly. For a tool with 4 parameters and no output schema, this 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 descriptions cover all 4 parameters (100% coverage). The description adds value by explaining that 'context' applies to every probe, that 'entities' first entry is the subject, and that 'models' defaults to workers-ai. This goes beyond the schema's basic descriptions.

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

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

The description uses specific verbs ('compare', 'probes', 'ranks') and identifies the resource ('AI visibility across multiple entities'). It distinguishes this tool from siblings like 'ai_visibility_check' by emphasizing side-by-side comparison and ranking, and provides a concrete competitive audit example.

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 the tool is 'useful for competitive AI-marketing audits' and gives a sample question. It implies when to use (multi-entity comparison) and the first entity as subject. It doesn't explicitly state when not to use, but the context is clear enough.

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

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

Adds critical behavioral details beyond annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, sources_failed field lists timeouts. 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 dense but well-organized: composite action, use case, behavioral notes, ecosystem clarification. Could be slightly trimmed but every sentence adds value.

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

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

Without an output schema, the description thoroughly explains the return structure (summary block fields, advisories, links, alternative versions) and covers edge cases (timeouts, partial failure). Complete for a complex tool.

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

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

Schema coverage is 100%, but description adds value by noting scoped packages are accepted (e.g., '@types/node'). This is a helpful detail beyond the schema's description.

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

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

Description clearly states it's a composite check for npm packages, specifying what it fans out across (deps.dev and bundlephobia) and exactly what it returns. Distinguishes from siblings as the only scanning tool for npm dependency evaluation.

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"' and gives a concrete example. Also clarifies NPM-only scope and directs other ecosystems to deps.dev directly.

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

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

Adds significant detail beyond annotations: embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, 200K character cap with truncation flag, and offset verification for quotes. All annotations (readOnlyHint, idempotentHint, etc.) are consistent and expanded upon.

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 clear and front-loaded with the purpose. It is concise (4 sentences) with each sentence adding value. Could be slightly more structured but overall effective.

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

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

Despite no output schema, description fully explains return format (passages with offsets and scores) and limits (200K chars, truncated and flagged). The use case, method, constraints, and complementary tool are all covered, making the tool self-explanatory.

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 adds behavioral context (embedding model, similarity metric, windowing, truncation) and usage hints for the query parameter, providing value 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?

Description clearly states the tool performs semantic search inside a fetched record, with concrete examples (SEC 10-K, article, tool result). Distinguished from siblings by focusing on searching within already-retrieved text, not global search.

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

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

Explicitly says use when the record is too large for the prompt, saving context by returning only relevant passages. Mentions pairing with ask_pipeworx_grounded for grounded generation. Does not explicitly state when not to use or list alternatives, but the context is clear.

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

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

The description discloses behavioral traits such as the OAuth requirement, SMS cap (10/day), webhook auto-disable after 10 failures, and that the webhook secret is returned only once. These go beyond the annotations, which state idempotent but not destructive. No contradictions with annotations; the description aligns with readOnlyHint=false and idempotentHint=true.

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

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

The description is well-structured with front-loaded key information, but it is somewhat lengthy. Each sentence adds value, and the use of bullet-like details in plain text is effective. Could be slightly more compact without losing critical details.

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

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

Given the complexity (3 params, nested objects, no output schema), the description covers prerequisites, types, and delivery channels thoroughly. However, it omits detailed description of the return value beyond the subscription id, and does not specify idempotency behavior (though hinted in annotations). This leaves some gaps for an AI agent expecting full context.

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

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

The description adds substantial meaning beyond the schema, with type-specific examples (e.g., sec_8k items codes, fred_series series_id) and detailed delivery constraints (phone verification, rate limits, webhook signing). Schema coverage is 100%, so the baseline is 3, but the description's richness in examples and constraints elevates it to 5.

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

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

The description clearly states the verb 'Create' and the resource 'proactive monitoring subscription', and the returned value 'new subscription id'. It distinguishes the tool from siblings like 'list_subscriptions' and 'unsubscribe' by focusing on creation.

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

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

The description provides clear context by specifying the prerequisite of a Pipeworx OAuth account and that anonymous/BYO cannot persist subscriptions. It implicitly guides use for setting up monitoring but falls short of explicitly stating when not to use this tool (e.g., for simply viewing alerts, use 'recent_alerts' instead).

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context by detailing the output structure (category-bucketed example questions) and the effect of the topic parameter. No contradictions.

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

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

The description is fairly long but highly informative, front-loading the core purpose and key usage instructions. While every sentence adds value, minor trimming could improve conciseness without losing clarity.

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

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

Given the tool's simplicity (1 optional parameter, no output schema), the description is fully complete. It explains the return format, invocation patterns, and placement in the workflow. No gaps remain for an agent to misuse the tool.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains the 'topic' parameter's purpose ('focus area') and gives concrete examples ('finance', 'pharma', 'betting'), which goes beyond the schema's generic description.

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

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

The description clearly states the tool is an onboarding entry point for learning about Pipeworx capabilities, returning category-bucketed example questions. It uses specific verbs ('suggest questions', 'returns') and distinguishes itself from meta-tools like ask_pipeworx by being the first tool to call when unsure.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides alternatives like learning meta-tools. Also explains when to pass a topic vs. no arguments, giving clear 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?

Description adds key behavioral details beyond annotations: it deactivates rather than deletes, preserves historical events, and enforces ownership. This aligns with annotations (idempotentHint true, destructiveHint false) and provides valuable 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?

Two concise sentences that front-load the action and constraints. No redundant or unnecessary information.

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

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

For a simple tool with one parameter, no output schema, and existing annotations, the description fully covers the purpose, effect, ownership, and data persistence, 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%, and the single parameter 'id' is well-described in the schema. The description does not add extra param details, so baseline 3 is appropriate.

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

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

The title 'Unsubscribe from Alerts' and description clearly state it cancels a subscription by ID. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description explicitly states ownership enforcement ('you can only cancel your own subscriptions') and that the row is deactivated, not deleted, which guides usage. It does not explicitly mention alternatives but provides sufficient 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 signal read-only, idempotent, and non-destructive behavior. The description adds rich behavioral context: two verification pipelines, the exact verdict set (confirmed, approximately_correct, refuted, inconclusive, unsupported, could_not_verify), the presence of a verification_error field, and critical caller guidance that could_not_verify must not be treated as evidence for or against the claim. It also clarifies the difference between unsupported and could_not_verify. 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 longer than typical, but it is front-loaded with example queries and every sentence carries useful information (usage, pipelines, verdicts, error semantics). It is well structured, but the length (especially the detailed path explanations and the lengthy caller warning) keeps it from a 5, which would be reserved for a truly minimal yet complete description.

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

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

Given the tool's complexity (two verification paths, multiple verdict values, error handling) and the absence of an output schema, the description is remarkably complete. It covers return content (verdict, actual value, citation, reasoning), explains failure modes (could_not_verify vs unsupported), and gives practical invocation guidance. An agent has enough to invoke and interpret 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 `claim` and `tolerance_pct` have clear, detailed descriptions in the input schema. The tool description itself does not add substantial parameter-level meaning beyond what the schema already provides; it mentions tolerance semantics indirectly via "exact percent-delta math" but the schema already explains defaults and overrides. Baseline 3 applies.

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

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

The description clearly states that the tool performs natural-language claim verification against authoritative sources, with explicit example phrasings like "fact check" and "verify the claim that…". It distinguishes itself from siblings by describing a two-path pipeline (SEC EDGAR for company financials, grounded pipeline for all other facts) and noting it replaces 4–6 sequential calls, so the agent knows exactly what this tool is for.

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

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

It explicitly says "Use whenever the agent needs to check whether something a user said is factually correct," which is a clear invocation guideline. It also explains that company-financial claims follow a fast path and any other claim falls through to the grounded pipeline. However, it does not name alternative tools or explicitly state when not to use it, so it stops short of a 5.

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