Data Sncf

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

Annotations declare read-only, open-world, idempotent, non-destructive. The description adds behavioral details: default model, BYO key for Anthropic, output structure (per-model scores, combined view). No contradictions.

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

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

Four sentences, front-loaded with purpose, no fluff. Each sentence adds essential information. Well-structured and easy to parse.

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

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

For a 4-parameter tool without output schema, the description covers what it returns (per-model score/confidence/signals/raw_response + combined view) and model options. Missing some specifics on output format, but adequate for selection.

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. The description adds value by specifying default model, supported models, and that _apiKey is passed directly to Anthropic. It enriches the schema without just repeating.

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 probes LLMs for visibility of an entity and returns a score. It specifies verb 'probe' and resource 'visibility'. While it doesn't explicitly distinguish from siblings like 'scan_competitor_ai_presence', the unique scoring and per-model detail make it clear.

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

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

The description mentions use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also explains when to use the free default model vs requiring an API key for Anthropic. However, it doesn't explicitly say when not to use it or compare to alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=False. The description goes beyond this by revealing the routing mechanism, argument filling, and the stable pipeworx:// citation URIs in the output, plus the performance note 'works on every tier, one fast call'. This adds useful behavioral context without contradicting annotations.

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

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

The description is relatively long but every sentence contributes: the opening directive, the routing explanation, examples, and positioning relative to siblings. It is well-structured and front-loaded with the most important usage guidance. Not as tight as a two-sentence description, but appropriately detailed for a complex routing 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?

Given there's no output schema, the description explains the return format (structured answer with citation URIs). It covers input (natural-language question), scope (current/historical data across many domains), and usage tiers. Together with annotations, this gives a comprehensive picture of the tool's behavior and limitations.

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 baseline is 3. The description adds example questions that illustrate the expected natural-language input, but this mirrors the schema examples and doesn't provide additional parameter semantics beyond what the schema already explains. No special value added over the structured field.

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

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

The description clearly states the tool's function: it routes questions to the right tool among 5,501 across 1,441 verified sources, fills arguments, and returns structured answers with citations. This specific verb+resource combination distinguishes it from siblings like ask_pipeworx_grounded and deep_research, making the purpose unmistakable.

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?

Usage guidance is explicit: it says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', and provides clear alternatives with conditions—use ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions. This directly answers when to use this tool vs others.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds that this is a full working router with no fallback, meaning it does not degrade to another tool. It also discloses the experimental nature and current equivalence to the stable version. While it doesn't detail response format or error behavior, the safety profile is well covered by annotations plus the added context about being identical to ask_pipeworx.

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

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

The description is dense but highly efficient, packed into two sentences plus a clarifying final sentence. Every clause adds meaningful information: purpose, scope, current state, usage instruction, and fallback behavior. It is front-loaded with the essential information about being a beta universal router.

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

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

Given the tool has no output schema, the description does a good job explaining what the tool is, its current behavior, and when to use it. The main gap is not describing the response shape, but it explicitly states the response shape is identical to ask_pipeworx, so an agent familiar with the sibling can infer everything. Considering the tool's complexity and rich sibling context, this is reasonably complete.

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

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

The schema has 100% coverage with all six parameters documented as aliases for 'question'. The description adds the crucial semantic that arguments are identical to ask_pipeworx, which is valuable because it tells the agent not to expect special beta-only parameters. Since the schema fully documents each parameter, the description's confirmation of identical arguments provides useful contextual assurance beyond the schema.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, a universal router with identical scope (same 5,501 tools, same arguments, same response shape). It explicitly differentiates from its sibling ask_pipeworx by noting experimental routing improvements, and distinguishes from other siblings by stating it is a full working router, not a fallback.

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

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

The description provides explicit usage guidance: use it exactly like ask_pipeworx when you want the newest routing, and notes that results are compared against the stable router. It also clarifies that no candidate is active right now so it currently matches ask_pipeworx exactly, giving clear context for when to select this over the stable sibling.

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 richly discloses behavioral traits beyond the readOnlyHint/openWorldHint/idempotentHint annotations: it returns explicit refusal reasons (not_in_source, no_tool_match, tool_error, etc.), only extracts from tool result to prevent hallucination, and costs an extra LLM call. This matches and extends 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 appropriately sized and well-structured: it opens with the core purpose, then explains the routing/mechanism, provides the exact return shape, lists refusal reasons, and closes with usage guidance and cost tradeoff. Every sentence adds value 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?

Given there is no output schema, the description fully explains the return format (answer, evidence, confidence, source, fetched_at, refusal_reason) and all possible refusal reasons. It covers success and failure scenarios, use cases, and cost, making it complete for a complex grounded-answer 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?

Input schema coverage is 100%, with the main parameter 'question' and five aliases clearly documented. The description doesn't add parameter-specific semantics but this is acceptable given the schema already explains the parameters in full; baseline 3 applies.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode' that extracts answers using only the tool result, returning evidence and confidence. It explicitly positions itself relative to the sibling ask_pipeworx by noting 'Same routing as ask_pipeworx' and the added grounded extraction, distinguishing it as the safer alternative for high-stakes reads.

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 usage guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on... and the agent must not invent facts' and 'prefer ask_pipeworx for casual lookups.' This clearly specifies when to use this tool versus the sibling ask_pipeworx, including cost tradeoff.

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, open-world, non-destructive behavior. The description adds extensive behavioral context: market resolution, classification, fan-out to multiple sources, edge cases like low-confidence matches, closed markets, wide spreads, cancellation rules, news fallback mechanisms, and response shapes. 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 comprehensive but excessively long, covering many scenarios and edge cases in dense detail. It is well-structured with section headers (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.), but the verbosity may hinder quick comprehension. Could be more streamlined while retaining key points.

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

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

Given the tool's complexity (multiple classifiers, source fan-outs, response shapes, error handling), the description is extremely complete. It addresses market match confidence, parent events, news fallback, safety measures, wide spread tradeability, cancellation rules, and more. No output schema, but return values are thoroughly explained.

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

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

All three parameters have schema descriptions, achieving 100% coverage. The description goes well beyond schema by detailing the market parameter valid forms (slug, URL, question text), depth options, and include_raw effects. Examples and notes significantly enhance understanding.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It defines inputs (slug, URL, or question text) and outputs (evidence packet + comparison). It distinguishes itself from sibling tools by focusing on Polymarket and Pipeworx data integration.

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 usage examples: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' While it does not directly compare to siblings like polymarket_edges, the context implies it is the go-to for initial research. Lacks explicit 'when not to use' but provides clear intent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds details: uses latest 10-K data, handles off-calendar fiscal years, returns sorted results and citation URIs. No contradictions.

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

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

Front-loaded with query examples, each sentence adds value. Slightly long but justified given the information density. Could be slightly trimmed without loss.

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 explains it 'Returns paired data + pipeworx:// citation URIs per entity.' Covers data sources, sorting, and typical use cases. While exact output structure is vague, it is adequate for the tool's role.

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

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

Schema coverage is 100% but description adds significant meaning: explains what each type returns, acceptable value formats (tickers vs drug names), min/max items, and sort behavior. Goes well beyond schema.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs, with concrete query examples. It distinguishes from sequential single-entity lookups, implying it replaces multiple calls to entity_profile or similar tools.

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

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

Explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides context on data sources per type but does not explicitly list sibling tools to avoid.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds specifics about return contents (fields/schema, themes, record count) and the pre-query role, which enriches transparency 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?

Single sentence, 15 words, front-loaded with core action. No redundancy or extra content. Every word earns its place.

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

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

With one parameter, rich annotations, and no output schema, the description sufficiently covers purpose, behavior, and usage. It could briefly mention example return format but is otherwise 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_description_coverage is 100%, with the parameter dataset_id already documented. The description adds minor context ('Dataset id from search_datasets') but does not significantly extend schema meaning, warranting the baseline score of 3.

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

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

The description clearly states it retrieves metadata (fields/schema, themes, record count) for one SNCF Open Data dataset. It distinguishes from siblings like search_datasets and query by specifying it's a pre-query step.

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

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

The description explicitly advises 'call before query to learn the column names,' providing clear usage context. It doesn't explicitly state when not to use or list alternatives, but the guidance is strong enough for correct invocation.

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?

Even though annotations already mark readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral context: non-open-web scope, parallel decomposition, findings packet structure, gaps[] never inventing answers, contradictions[] for standard/thorough, semantic excerpting, citation_uri resolvability, paid plan requirement for depth:thorough, and expected latency 15-90s. It complements annotations without contradicting them.

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

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

The description is long but information-dense and structured as a flowing paragraph that front-loads the most critical usage constraint (account required) and key differentiator (structured data, not open-web). Every sentence carries a distinct fact, but length could be trimmed without losing value, so a 4 is appropriate.

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 complex tool with 2 params, no output schema, and full annotations, the description thoroughly compensates: it explains return shape (findings packet), behaviors per depth tier, limitations (empty gaps for unsupported topics), citation resolvability, and latency. It answers likely user questions without needing an output schema.

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

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

Schema coverage is 100%, so the schema already documents both parameters well. The description adds meaningful context beyond the schema by explaining what quick/standard/thorough actually do (e.g., gap recovery hop for standard, lead chasing for thorough) and how the question parameter is decomposed into facets. This adds practical semantics over the raw schema.

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

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

The description clearly states the tool performs grounded multi-source research over Pipeworx's 1441 structured data sources, decomposing questions and routing to 5,501 tools in parallel. It explicitly distinguishes itself from open-web search and sibling tools like ask_pipeworx, making its purpose and scope unmistakably clear.

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

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

The description provides explicit when-to-use guidance: best for broad/multi-part questions over structured data, while for single lookups or breaking/current-news topics it directs users to use ask_pipeworx instead. It also details depth-tier behaviors (quick, standard, thorough) including gap recovery and lead chasing, giving concrete decision criteria.

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

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

Annotations already indicate safe, read-only operation. The description adds valuable context: returns full input schemas with examples, ready to call directly. No contradictions.

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

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

Description is long with an extensive list of domains and examples. While front-loaded with purpose, the verbosity could be trimmed (e.g., domain list). Earns its place but not maximally concise.

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

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

Given 6 parameters (5 aliases) and no output schema, the description adequately explains return value (names, descriptions, schemas with examples). Sufficient for a discovery tool with good annotations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal parameter meaning beyond schema—lists aliases and examples but doesn't explain beyond what's already in schema.

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

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

The description clearly states 'Find tools by describing the data or task,' providing a specific verb and resource. It distinguishes itself from siblings like 'query' or 'search_datasets' by positioning as a discovery layer, especially with 'Call this FIRST'.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools.' Lacks explicit when-not-to-use but contextual enough.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: it fans out across multiple data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), describes return fields (cik, recent_filings, fundamentals, patents, news, LEI), and notes that patents may soft-fail due to API sunset. This goes well beyond the annotations.

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

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

The description is somewhat long but well-structured with a bulleted list of return values. Examples are front-loaded, which helps the agent quickly understand the tool's scope. A few sentences could be trimmed without losing meaning, but overall it's efficiently organized.

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

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

Despite no output schema, the description thoroughly explains return values (cik, recent_filings with URIs, fundamentals sorted by period_end, patents with caveat, news fallback, LEI). It covers input constraints, data sources, and known limitations. For a complex tool, this is highly complete.

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

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

Schema coverage is 100%, and the schema already describes both parameters (type and value) with enums and examples. The description reinforces that type is only 'company' and value can be ticker or CIK, and reiterates that names are not supported. While it adds useful context, the schema already does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It provides numerous example queries and distinguishes itself from chaining multiple single-source lookups. The verb 'profile' and resource 'US public company' are 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 says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies when not to use: 'names not supported (use resolve_entity first).' This provides clear when-to-use and alternative guidance.

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

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

Annotations already provide destructiveHint=true, so description's 'Delete' adds no new behavioral info. It adds context about use cases, but not unique behavioral traits beyond annotations.

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

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

Two sentences: first states purpose, second provides usage guidance. No wasted words, front-loaded with key information.

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

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

Simple single-param tool with annotations covering destructiveness. Missing mention of idempotency (idempotentHint=true) or behavior on missing key, but completeness is high given tool simplicity.

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

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

Schema coverage is 100% with description 'Memory key to delete'. Description only says 'by key', adding no extra meaning beyond schema. 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?

Description clearly states 'Delete a previously stored memory by key', specifying verb and resource. It distinguishes from siblings like remember and recall by pairing them, indicating this is the deletion counterpart.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Pairs with remember and recall, guiding agent on 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds: fetches page, extracts title/description/key links, emits standard markdown format. No contradiction; adds process and output details.

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

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

Two sentences, front-loaded with main action. The second sentence lists use cases effectively. Could be slightly more concise but 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?

Covers input, process, output format, and use cases. No output schema needed as description explains output is a single text blob. Complete for a simple generation tool.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds that max_links defaults to 25 and max 50, providing additional meaning beyond schema.

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

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

The description clearly states 'Generate a production-ready llms.txt file for any URL' with a specific verb and resource. It distinguishes this tool from siblings by focusing on the standard llms.txt generation, unlike scanning or research 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?

Explicit use cases are listed: getting a client's site indexed, drafting for own project, auditing competitors. Does not explicitly state when not to use, but the specificity provides clear context.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds return field details and optional include_inactive 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?

Two sentences, no filler, front-loaded with the action. 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 simple tool with 1 parameter, good annotations, and no output schema, the description covers functionality, use cases, and return fields adequately.

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

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

Schema coverage is 100% for the only parameter (include_inactive). Description does not add extra meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

Clearly states the action ('List the caller's active subscriptions') and specifies the returned fields (id, type, params, etc.). Distinct from sibling tools like subscribe/unsubscribe.

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

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

Explicit use cases provided: review before adding more or to find an id to cancel. Does not include negative cases or alternatives, but context is clear.

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

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

Annotations are minimal (readOnlyHint=false etc.), but the description supplies behavioral context beyond them: rate limiting ('Rate-limited to 5 per identifier per day'), quota impact ('doesn't count against your tool-call quota'), the claim_token flow ('Filing without an account returns a claim_token; pass it back later...'), and that the team 'reads digests daily and signal directly affects roadmap.' No contradiction with annotations.

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

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

The description is long, but it covers multiple complex aspects (types, exclusions, token flow, rate limits, quota). Every sentence is informative; however, a few sentences like 'The team reads digests daily and signal directly affects roadmap' are motivational rather than directly actionable, and the block is one dense paragraph without structural breaks. It earns a 4.

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 (four parameters, optional claim_token, multiple feedback types) and the absence of an output schema, the description provides complete coverage: purpose, when/when-not, token semantics, rate limits, and expected response behavior. An agent can use it correctly without further clarification.

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

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

Although the input schema already describes all four parameters (100% coverage), the description adds important usage semantics: it clarifies the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), explicitly instructs users to 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' and explains that claim_token can be used 'with no other arguments.' This goes beyond the schema's per-parameter 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 opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which is a clear verb+resource statement. It explicitly enumerates the feedback types (bug, feature, data_gap, praise) and distinguishes this from sibling tools like ask_pipeworx or query by framing it as reporting issues about Pipeworx itself.

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

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

The description states exactly when to use: '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).' It also provides an explicit exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This satisfies 'explicit when/when-not/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 data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). Provides full transparency.

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

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

Three sentences with no fluff: first sentence states function, second lists use cases, third gives details. Very efficient and well-structured.

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

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

For a simple tool with one optional parameter and no output schema, the description covers return values, usage context, caching, and data source. No obvious 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 already covers the single 'window' parameter with enum and description. The description adds context on how shorter vs longer windows affect what's surfaced, which adds value beyond schema.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a window, and provides three specific use cases. It distinguishes from sibling tools by focusing on aggregate trending data.

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

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

Explicitly lists three situations where the tool is useful (discovering hot data sources, confirming popular tool, checking alignment). Lacks explicit when-not-to-use or alternatives, but context is clear.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive hints. The description adds extensive behavioral details: walks child markets, checks order and partition sums, performs fill checks against live order book, filters partitions with placeholders, and uses semantic similarity to prevent mismatches. 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 dense but front-loaded with the core purpose and modes. While thorough, it could benefit from clearer section breaks or bullet points to improve readability. However, every sentence adds value and avoids redundancy.

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

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

Despite lacking an output schema, the description details the response structure (opportunities array, partition_check object, fill_check fields) and references related tools. For a complex tool with no output schema, it is remarkably complete, covering behavior, constraints, and edge cases.

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 meaning: explains what event slugs look like, that full URLs work, what topic strings are used for, and how the behavior differs between parameters. It provides examples and clarifies internal logic like semantic anchor and partition filter.

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: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (trending_scan, event, topic) with explicit details.

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

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

The description provides explicit guidance on when to use each parameter: no args for trending scan, event for a specific market slug, topic for cross-event scanning. It also mentions an alternative (polymarket_fill_risk for custom sizing) and conditions like when not to trade.

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

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

The description goes far beyond the annotations (readOnlyHint, idempotentHint, etc.) by detailing the three model families, caching behavior (1h at KV level), tradeable-edge knobs, response structure including diagnostics, and per-opportunity fields. It adds substantial behavioral context that aids correct invocation and interpretation.

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

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

The description is well-structured with clear sections (model families, opportunity fields, knobs, response top-level) and front-loads the primary use case. While lengthy, every sentence adds value. Minor verbosity in the model family details could be trimmed slightly, but overall it is appropriately detailed 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?

The description comprehensively covers all aspects needed for an AI agent to use the tool correctly: input knobs, output structure (by_segment, fed_candidates, _diagnostics), per-opportunity fields, caching behavior, and filter logic. Given the lack of an output schema, the description fully compensates, leaving no critical 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?

With 100% schema description coverage, the baseline is 3. The description adds extra meaning by explaining how parameters like min_kelly, max_spread_pp, and min_partition_leg_kelly interact with the logic (e.g., min_kelly skips small opportunities, min_partition_leg_kelly filters thin partitions). This context enhances understanding 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 clearly states that the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and is built for 'what should I bet on today' discovery. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on model-driven, structural arbitrage, and concentrated longshot segments, making its purpose specific and actionable.

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

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

The description explicitly frames the tool for daily betting discovery ('what should I bet on today'), providing clear context for when to use it. While it does not explicitly list alternatives or when not to use, the detailed explanation of segments and knobs implies usage scenarios. The omission of direct exclusions prevents a score of 5.

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

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

The description adds significant behavioral context beyond annotations: it details the output structure (tracked, expired, snapshot_dates), computation of decay and trend, sign conventions, and limitations (TTL, cache-miss behavior). Annotations only state idempotence and read-only, which are supported.

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. It is front-loaded with purpose, and each sentence adds value. Slight verbosity could be trimmed, but overall 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?

Despite no output schema, the description fully explains the return format and fields. It covers limitations and edge cases, making it complete for an AI to understand usage and results.

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

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

Schema coverage is 100% with parameter descriptions. The description adds defaults and constraints (clamp, window families) and explains the meaning of window in context of snapshot families, enhancing the schema.

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

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

The description clearly states it provides edge persistence and decay telemetry built from daily snapshots, answering a specific question about edge duration. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis.

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

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

The description explains when to use the tool (to assess edge persistence and decay) and provides concrete examples (fresh vs. old wide edge). It does not explicitly list when not to use or alternatives, but the context is clear enough for an AI to decide.

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 include readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description reinforces that it's a read-only check (no side effects) and adds behavioral details: walks the order book, returns verdicts (clean/degraded/cannot_fill), and alerts about forced directional risk. No contradiction.

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

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

The description is relatively long but well-structured: starts with purpose, then required params, then mode explanations, return fields, and usage guidance. Every sentence adds value, though it could be slightly more concise. Front-loaded effectively.

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, four parameters, no output schema), the description is remarkably complete. It lists all return fields for both modes, explains pitfalls (thin legs, forced directional risk), and provides practical guidance. Fully carries the burden of explaining behavior.

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

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

Schema description coverage is 100%, giving baseline 3. The description goes beyond by explaining default sizes (1000), how size_usd is interpreted differently for single-market vs basket, and the auto-default logic for side in basket mode. Adds meaningful context beyond schema.

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

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

The description clearly identifies the tool as a 'realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishing between single-market and basket modes with specific return fields (top_of_book, vwap_fill_price, etc.). It differentiates from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk and book depth.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It warns about when not to use it: theoretical overround on thin books is not capturable, and partial basket fills convert arb into unhedged directional position. Provides clear context and alternatives.

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

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

The description extensively discloses behavioral traits beyond annotations, including response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters), and edge case explanations. No contradiction with annotations; annotations are consistent.

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

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

The description is long and detailed, covering response fields and safety warnings thoroughly. It is front-loaded with the core purpose, but later sections could be more succinct. Every sentence provides useful information, but the length may reduce readability for an agent scanning for quick understanding.

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

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

Given no output schema, the description fully explains return values (leg prices, top spreads, safety fields), temporal alignment, and skipped comparison counters. It covers what the tool does, how to interpret results, and edge cases like compatibility_warning scenarios. No missing critical information.

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

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

With 100% schema coverage, the description adds value by explaining how topic allows 10 shortcuts, how explicit tickers override defaults, and how parameters interact. This goes beyond the minimal schema descriptions, though some redundancy exists due to schema already listing values.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question', clearly identifying the tool's unique function. It distinguishes this from siblings like polymarket_arbitrage by focusing on cross-venue comparison. The explanation of two modes (topic shortcuts and explicit pairing) adds specificity.

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 describes when to use each mode and warns that real spreads are rarer than the shortcut list suggests, guiding appropriate usage. It does not explicitly contrast with alternative tools but the sibling list and context imply this is the primary cross-venue comparison tool. A direct 'when to use vs alternatives' statement would improve clarity.

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, so the description is not burdened with safety disclosure. The description adds value by detailing the query language (ODSQL) and supported clauses (filter, aggregate, sort, paginate), enhancing understanding of capabilities 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 a single sentence that front-loads the core purpose and succinctly lists supported operations with parenthetical grouping. Every word is necessary and 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?

With no output schema, the description omits the return format, but for a query tool the return of records is implicit. It covers all major functional aspects (filter, aggregate, sort, paginate) and the prerequisite of specifying a dataset_id. Sufficient for most use cases given good annotations.

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

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

All 8 parameters are fully described in the input schema (100% coverage). The description groups parameters into conceptual categories (filter, aggregate, sort, paginate) but does not add new semantic details beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Query', the resource 'SNCF Open Data dataset', and the specific ODSQL operations (filter, aggregate, sort, paginate). This distinguishes it from sibling tools like 'search_datasets' which find datasets, not query records.

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

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

The description implies usage for querying data with ODSQL, but does not explicitly state when to use this tool versus alternatives like 'search_datasets' or 'search_within'. No exclusions or comparative guidance are provided.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false. Description adds scoping detail ('Scoped to your identifier') and lifecycle pairing, which adds value beyond annotations.

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

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

Three sentences, front-loaded with the main action. Every sentence adds value without redundancy.

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

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

For a simple read-only retrieval tool with one optional parameter and no output schema, the description covers use case, scoping, and lifecycle pairing comprehensively.

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

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

Schema coverage is 100% with a single optional key parameter. Description reinforces the schema's description (e.g., 'omit the key argument'). Baseline 3 is appropriate; no additional parameter semantics beyond schema.

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

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

Clearly specifies verb ('Retrieve a value previously saved via remember, or list all saved keys') and resource (saved values/keys). Distinguishes from siblings like 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?

States when to use: 'to look up context the agent stored earlier'. Mentions pairing with remember/forget. Lacks explicit when-not-to-use or alternative tools, but context is clear.

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

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

The description discloses that setting mark_read:true flags returned events as read, affecting subsequent calls—a state-modifying behavior. However, the annotations declare readOnlyHint=true, which implies no writes. This contradiction between description and annotation misleads the agent about the tool's side effects, leading to a low score.

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, front-loading the core purpose and then efficiently covering key features (filters, mark_read, polling). Every sentence adds value without redundancy or unnecessary detail.

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

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

Despite no output schema, the description explains what fields each alert carries (source, citation_uri, raw payload). It also mentions polling suitability and an alternative endpoint. For a tool with 5 optional parameters, this is sufficiently complete, though it could briefly note the structure of the payload.

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

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

Schema coverage is 100%, providing baseline parameter info. The description adds meaningful context beyond the schema: it gives an example for type ('sec_8k') and explains the effect of mark_read on future calls ('so the next call only shows newer ones'). This extra guidance moderately enhances parameter understanding.

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

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

The description clearly states it pulls fired events from the subscription feed and returns recent alerts with specific fields (source, citation_uri, raw payload). It distinguishes itself from sibling tools like list_subscriptions, which list subscriptions themselves, not events. The verb 'pull' and resource 'fired events' are 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 implies when to use this tool (to check recent alerts) and mentions an alternative GET endpoint for scripts/dashboards, but does not explicitly state when not to use it or provide exclusions compared to other tools. The context is clear enough for an agent to infer typical usage.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the parallel fan-out to multiple sources, fallback behavior (GDELT→GNews on rate limit/5xx), USPTO soft-fail, and the return structure (changes[] grouped by source, total_changes, citation URIs). No contradictions with annotations.

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

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

The description is a single, slightly dense paragraph but front-loaded with intuitive example queries. Every sentence adds useful information. Could be slightly improved with bullet points or separation, but is efficient overall.

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

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

Despite lacking an output schema, the description adequately describes the return structure (changes grouped by source, counts, citation URIs). It covers sources, fallbacks, soft-failures, and the alternative tool. For a tool with good annotations and moderate complexity, this is sufficiently complete.

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

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

Schema coverage is 100% but the description enriches meanings: 'since' accepts ISO date or relative shorthand ('7d', '30d', '3m', '1y') with example values, and 'value' can be ticker or zero-padded CIK. This goes beyond the schema's basic type/format 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 concrete example queries and states the tool's purpose as a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It specifies the data sources (SEC EDGAR, GDELT→GNews, USPTO) and explicitly contrasts with sibling tool entity_profile, making it easy to distinguish.

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 an explicit alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also explains when the GDELT→GNews fallback occurs. However, it does not list specific scenarios to avoid using this tool.

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

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

Disclosures beyond annotations: 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' No contradictions with annotations (idempotentHint true, destructiveHint false).

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

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

Four concise sentences: core purpose, usage guidance, storage mechanism, retrieval pairing. No unnecessary words; front-loaded with key action.

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

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

Completely covers purpose, usage, persistence behavior, and integration with sibling tools. No output schema needed for this simple write operation.

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

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

Schema has 100% coverage with descriptions. Description adds example key patterns (subject_property, target_ticker) and specifies value as 'any text', providing extra context.

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

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

The description uses specific verbs ('Save data the agent will need to reuse later') and resources ('key-value pair'), clearly distinguishing from sibling tools like recall and forget.

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

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

Explicitly states when to use ('when you discover something worth carrying forward'), provides context (authentication persistence), and pairs with recall/forget for retrieval/deletion.

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, and openWorld. The description adds useful context about internal behavior: 'Each call cascades through several lookup endpoints internally' and replaces 2-3 manual lookups. This informs the agent about the tool's complexity and cost, going beyond the annotation hints. 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 longer than average but well-structured with 'SUPPORTED TYPES' subdivision. Every sentence contributes information, and the opening examples are attention-grabbing. It earns a 4 rather than 5 due to slight verbosity in repeating company/drug 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?

With no output schema, the description takes responsibility for explaining return values, and it does so thoroughly for both types (ticker, CIK, company_name; RxCUI, ingredient, brand) plus citation URIs. It also clarifies input formats for each type. The only gap is lack of error/failure behavior, but this is acceptable for a lookup tool.

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

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

Schema coverage is 100%, so the schema fully documents both parameters. The description enhances semantics with concrete examples (AAPL, 0000320193, ozempic) and notes auto-disambiguation for company inputs, which is not in the schema. This adds value without being redundant.

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

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

The description opens with concrete example queries and states the core function: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' This is a specific verb+resource+outcome, and it clearly distinguishes from sibling tools like entity_profile or compare_entities by focusing on ID resolution.

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 direction: 'Use FIRST whenever you have a name but need an ID.' This gives a clear when-to-use rule and implies it should be used before other tools that expect identifiers. It also enumerates supported entity types, helping the agent decide which type to pass.

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

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

Annotations already indicate read-only and idempotent. The description adds significant behavioral context: it internally calls ai_visibility_check, ranks by score, and returns score, confidence, and signal density per entity. 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?

Three concise sentences, front-loaded with the primary action. Every sentence contributes meaningful information without redundancy.

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

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

Given full schema coverage and no output schema, the description sufficiently covers return format (ranked list with score, confidence, signal density), internal mechanism, and use case. No gaps identified.

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

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

Schema has 100% description coverage, so parameter basics are clear. The description adds value by explaining the 'entities' array: the first entity is treated as the subject for narrative, and the rest as competitors, which aids correct invocation.

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 verb (compare, probe, rank), resource (AI visibility across entities), and distinguishes from siblings like ai_visibility_check by emphasizing side-by-side comparison. The example use case reinforces clarity.

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

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

Provides explicit use case for competitive AI-marketing audits with a concrete question. However, it lacks guidance on when not to use this tool versus alternatives like ai_visibility_check or compare_entities.

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

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

Annotations already indicate safe, idempotent, read-only. Description adds composite nature, fan-out behavior, partial failure degradation with sources_failed, and timing caveat (5-30s for new version). 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 comprehensive and well-structured, front-loaded with purpose. Every sentence adds value, though slightly long; could be marginally shorter without loss of meaning.

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 composite tool with multiple data sources, partial failure modes, and no output schema, the description covers all necessary context: return fields, ecosystem scope, performance caveats, and fallback guidance for other ecosystems.

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

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

Schema coverage is 100% with clear descriptions for both parameters. Description repeats schema info (scoped packages, default version) without adding new semantics beyond what schema provides. Baseline 3 is appropriate.

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

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

Clearly states it's a composite check for 'should I add this npm package to my project' using deps.dev and bundlephobia. Unambiguous verb and resource, distinct from all 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?

Explicitly says when to use: 'whenever an agent asks is X safe/popular/small or what does adding lodash cost me.' Also notes NPM ecosystem only and directs to deps.dev:version for other ecosystems, and mentions partial failures.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety and idempotency. The description adds behavioral context by listing the return structure (dataset_ids, titles, themes, record counts) but does not disclose rate limits, authentication needs, or empty result behavior. With annotations, the description provides adequate but minimal extra transparency.

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

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

The description is two sentences with no superfluous words. It front-loads the core action and immediately lists return fields and usage hints. Every word contributes to understanding.

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

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

Given no output schema, the description adequately explains what is returned. It covers purpose, return structure, and parameter examples. Minor omissions like pagination behavior are already in the schema. The tool is relatively simple and the description is complete for its complexity.

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

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

Schema coverage is 100% with each parameter described. The description adds value by providing concrete keyword examples (train schedules, stations, punctuality) that go beyond the schema's generic 'Keyword(s) to search dataset titles/descriptions.' This enriches understanding of appropriate query values.

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

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

The description clearly states the tool searches SNCF Open Data datasets by keyword, lists example keywords, and specifies returned fields (dataset_ids, titles, themes, record counts). It distinguishes from siblings like dataset_info and query by indicating that dataset_ids can be passed to those tools.

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

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

The description explicitly tells when to use the tool (keyword search for datasets) and provides guidance on next steps (pass dataset_ids to query/dataset_info). It does not explicitly state when not to use it or mention specific 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 safe read operations. The description adds concrete behavior: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation flag, and output includes character offsets and similarity scores.

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 with no fluff. Core purpose front-loaded, followed by use case and technical details. Every sentence adds value.

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

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

Given the tool's purpose, parameters, and annotations, the description covers input constraints, algorithmic details, output structure, and truncation behavior. No output schema exists, but description adequately informs the agent.

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

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

Schema has 100% coverage with descriptions for all 3 parameters. The description adds example queries and explains limit default, but doesn't provide significant new semantics beyond the schema.

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

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

The description clearly states it performs semantic search inside a retrieved document, with specific examples (SEC 10-K, article) and distinguishes it from sibling tools like ask_pipeworx_grounded.

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

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

Explicitly says when to use: when record is too large for prompt. Also mentions pairing with ask_pipeworx_grounded for grounding over passages, and notes it saves context.

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

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

Annotations indicate readOnlyHint=false (write), idempotentHint=true, destructiveHint=false. The description adds operational details: SMS cap (10/day), webhook auto-disable after 10 failures, phone verification requirement, and one-time webhook secret. However, it does not clarify idempotency behavior (e.g., whether re-subscribing with same params creates duplicate). No annotation 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 comprehensive but somewhat lengthy. It is well-structured with clear sections: purpose, prerequisite, types, delivery channels. Every sentence adds value, but could be slightly more concise without losing detail.

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

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

Given the absence of an output schema, the description mentions the return of a subscription ID and, for webhook, a one-time secret. It covers most behavioral aspects (prerequisites, type-specific params, delivery options, limits). Missing details on error responses or duplicate subscription handling, but adequate for typical usage.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds rich, type-specific examples (e.g., sec_8k with ticker and items, polymarket_edge with topic and min_spread_bps) and detailed delivery channel behavior (email pattern, SMS E.164, webhook signing). This significantly extends the schema's minimal descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It uniquely identifies the resource (subscription) and action (create), and differentiates from siblings like unsubscribe and list_subscriptions through types and delivery details.

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 requires a Pipeworx OAuth account and notes that anonymous/BYO cannot persist subscriptions. It provides guidance on when to use each subscription type with examples, but does not explicitly exclude scenarios where alternatives like recent_alerts or ask_pipeworx would be better suited.

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 and idempotentHint. Description adds behavioral detail: returns example questions with exact tool+argument shape, drawn from live catalog. No contradictions. Adds value beyond annotations.

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

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

Description is well-structured with front-loaded trigger phrases and parentheses. Dense but every sentence adds value. Slightly long but appropriate for the complexity.

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

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

No output schema, but description explains return format clearly. Covers all necessary context: when to use, what it returns, how to call, and examples. Complete for the tool's purpose.

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

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

Schema coverage is 100% with description for topic parameter. Description adds context: 'Omit for a cross-category spread', lists example topics, and explains behavior with and without argument. Highly enhances schema.

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

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

The description clearly states it is an onboarding entry point that returns category-bucketed example questions with exact tool calls. It distinguishes from siblings by stating 'Use this FIRST' and listing what it covers, differentiating it from specialized tools like ask_pipeworx or entity_profile.

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

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

Explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and 'or to learn how to call the meta-tools'. It does not explicitly state when not to use, but the context is clear.

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

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

Discloses key behavior beyond annotations: row is deactivated (not deleted) and historical events remain accessible. Annotations already indicate non-destructive and non-read-only, so description adds value.

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

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

Two succinct sentences, front-loaded with action, no filler words. Earns its place 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?

For a simple tool with 1 param and no output schema, the description fully covers usage constraints and post-invocation state. No missing context.

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

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

Schema covers id with description 'Subscription id (uuid) returned by subscribe.' Description adds no param-specific info beyond 'by id', which is already implied. Schema coverage 100% sets baseline at 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?

Clear verb-resource pair: 'Cancel a subscription by id.' 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?

States ownership enforcement ('only your own subscriptions') and the soft-delete behavior, helping the agent understand when and how to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint=true, destructiveHint=false. The description adds rich behavioral context: dual verification paths (SEC EDGAR vs grounded pipeline), exact percent-delta math for financial claims, verbatim evidence, and the output (verdict, actual value, reasoning). It also notes that it replaces 4–6 sequential calls, which is not 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 detailed and well-structured, starting with example queries, then explaining the two paths. Every sentence adds value, though some redundancy exists (e.g., repeating 'grounded pipeline'). Minor reduction could improve conciseness.

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

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

Given the tool's complexity (two verification paths, multiple data sources), the description covers claim types, process, return values (verdict, actual value, reasoning). No output schema exists, but the output is adequately described. No additional context is needed beyond what's provided.

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

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

Input schema has 100% coverage with descriptions for both parameters. The description adds context (tolerance from wording, default 5% cap) but does not significantly extend beyond 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 uses specific verbs ('validate', 'fact check', 'verify') and clearly identifies the resource ('natural-language claim verification against authoritative sources'). It distinguishes between company-financial claims (via SEC EDGAR) and other claims (via grounded pipeline), differentiating it from sibling tools like ask_pipeworx or deep_research.

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

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

The description explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It explains the two verification paths but does not explicitly exclude scenarios or mention alternatives. More explicit when-not-to-use guidance would improve clarity.

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