Data Montgomery

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

Annotations (readOnlyHint, idempotentHint, openWorldHint) already convey safety. Description adds specifics: callers provide API key for Anthropic (BYO key), returns per-model score/confidence/signals/raw_response. No contradiction; adds payment model and return structure 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 including use cases. No filler; every word adds value. Information is front-loaded: purpose, then default behavior, then optional key, then return format.

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?

All 4 parameters are described in schema. Description covers return structure (per-model + combined) and use cases. No output schema exists, but description explains outputs adequately. Tool complexity is moderate, and description is fully sufficient.

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

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

Schema has 100% description coverage. Description adds value by stating default model (Workers AI Llama-3.3-70b free) and that _apiKey enables Anthropic probing at caller's cost. This supplements schema meaningfully.

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

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

The description specifies a unique action (probe LLMs for visibility) and resource (business/brand etc.), with output format and use cases. It distinguishes from sibling tools like 'ask_pipeworx' and 'scan_competitor_ai_presence' by focusing on visibility scoring across models.

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

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

Clearly states when to use: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Mentions default model is free and optional Anthropic requires API key. Lacks explicit exclusion of alternatives but provides clear context for appropriate use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds useful behavioral context beyond annotations: it says the tool routes to one of 5,708 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and that it does not produce hallucination-resistant verbatim evidence (that is reserved for ask_pipeworx_grounded). This meaningfully enriches the behavioral profile.

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

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

The description is front-loaded with the key directive ('PREFER OVER WEB SEARCH') and scope, followed by examples and clear escalation paths. It is somewhat long, but each sentence contributes to selection, invocation, or behavior. The structure is logical: preference, what it does, when to use, when not to use, examples.

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 fills the gap by stating it returns 'structured answer with stable pipeworx:// citation URIs.' It covers default usage, alternatives with conditions, applicable domains, and example questions. Nothing an agent needs to decide whether or how to call this tool is missing.

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

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

Schema description coverage is 100%: the schema already documents 'question' and its five aliases (q, text, input, query, prompt). The description reinforces that the parameter is a natural-language question and gives examples, but it does not need to add parameter-level detail beyond what the schema provides. Baseline 3 is appropriate since the schema carries the parameter-documentation burden.

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

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

The description states a specific verb ('routes the question') and a concrete resource: one of 5,708 tools across 1,494 verified sources. It explicitly names the domains it covers and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, so an agent can tell them apart without opening schemas.

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

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

The description gives explicit usage guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with specific conditions for ask_pipeworx_grounded and deep_research. It even provides trigger phrases ('what is', 'look up', 'find') and examples, leaving no ambiguity about when to select 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?

The description goes well beyond the annotations by disclosing that candidate routing improvements are enabled live whenever under test, that no candidate is active now, and that it currently matches ask_pipeworx exactly. It also clarifies that this is not a thin wrapper or fallback: 'Falls back to nothing — this IS a full working router.' This gives the agent an accurate model of the tool's runtime state and behavior.

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

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

The description is efficiently written and front-loaded with the most important fact—beta version of ask_pipeworx and identical universal router. Every sentence earns its place: the current candidate status, the matching behavior, the usage instruction, and the reassurance that it is a fully working router. No filler or redundancy.

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

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

For a single-question-parameter tool with rich annotations and no output schema, the description is complete. It explains the tool's relationship to ask_pipeworx, its current beta state, what the response shape is comparable to, and why an agent might choose it. The annotation set already covers read-only, idempotent, and non-destructive behavior, so nothing critical is missing.

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

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

Schema description coverage is 100%, with every alias for 'question' documented in the input schema. The description adds no new parameter-level semantics beyond saying it takes 'the same arguments' as ask_pipeworx, which is useful context but not meaningfully more than the schema already 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?

The description states exactly what this tool is: a beta version of ask_pipeworx, an identical universal router over the same 5,708 tools with the same arguments and response shape. It clearly distinguishes itself from ask_pipeworx by being the experimental edge where candidate routing improvements are tested live. The purpose is specific, unambiguous, and well-scoped.

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

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

The description gives explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing,' and references the stable router as the comparison point for routing decisions. It does not explicitly state when NOT to use it, but the contrast between the stable router and the experimental edge implies a reliability tradeoff. The guidance is strong but stops short of a full when/when-not exclusion list.

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

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

Annotations cover readOnly, openWorld, idempotent, and non-destructive semantics, so the bar for added value is lower. The description exceeds it by disclosing the exact success return shape, the explicit refusal structure with specific refusal_reason enum values, the rule that extraction uses ONLY the tool result, and the extra LLM call cost.

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

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

Every sentence earns its place: mode definition, routing, extraction guarantee, success/refusal return shapes, use cases, and cost tradeoff. The summary is front-loaded and the refusal enum is compactly listed.

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

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

With no output schema, the description compensates by fully describing both success and refusal returns, listing failure reasons, and explaining when to prefer the sibling. Nothing an agent needs to decide whether to call it or interpret its result is missing.

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

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

Schema coverage is 100% and every parameter is an alias for the same 'question' string, so the schema already documents semantics fully. The description does not add parameter-level detail beyond saying the tool routes and fills arguments, which is already implied by 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 a hallucination-resistant answer mode for high-stakes reads, with a specific verb ('answer') and a defined resource (tool results routed from 5,708 tools across 1,494 sources). It distinguishes itself from the sibling ask_pipeworx by detailing the grounded extraction behavior and by naming ask_pipeworx as the cheaper alternative.

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: whenever the answer will be quoted, cited, or acted on, and the agent must not invent facts. It also gives a concrete contrast with ask_pipeworx, recommending the sibling for casual lookups because of the extra LLM call cost.

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

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

The description extensively covers internal behavior: fan-out patterns, response shapes, resolver contract, parent event extraction, news fallback handling, safety mechanisms for low-confidence and closed markets, wide spread handling, and cancellation rule parsing. This far exceeds the annotations which only declare readOnly, openWorld, idempotent, and non-destructive.

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

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

The description is thorough but verbose, containing extensive examples and edge-case explanations that could be condensed. It front-loads the purpose and usage, but the detailed fan-out examples and resolver contract text bloat the length.

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

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

Despite no output schema, the description fully documents the response structure including market fields, analysis block, evidence keys, resolver confidence, parent event info, news fields, and cancellation rules. It covers all relevant edge cases and technical details.

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 (market, depth, include_raw) are fully described in the schema with 100% coverage. The description adds substantial context: market accepts slug, URL, or question text; depth's 'quick' vs 'thorough' behavior; include_raw's impact on response size. This greatly enriches the schema definitions.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, resolves, classifies, and returns evidence. It explicitly lists use cases like 'should I bet on X' distinguishing it from sibling tools like polymarket_edges.

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

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

The description provides explicit usage scenarios and examples for different bet types. It includes guidance on when to trust results (high/medium match confidence) and when analysis is suppressed. However, it does not directly contrast with sibling tools or state when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), correct handling of fiscal years, and sorting by primary metric. 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 concise yet information-dense, starting with common query patterns then stating the core function, preference rule, data details, and output summary. No redundant sentences; every element 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?

Despite no output schema, the description explains the output format (paired data + pipeworx:// citation URIs) and data sources. It covers key behavioral aspects for a comparison tool, though it lacks details on rate limits or error handling, which are acceptable for this 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 coverage is 100% with both parameters described. The description adds real-world examples for parameter values (e.g., tickers for companies, drug names) and explains the data behind each enum option, providing useful context 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 the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call. It provides example user phrases and explicitly distinguishes from sequential single-pack lookups, differentiating it from sibling tools like 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?

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups' when comparing entities, giving clear when-to-use guidance. It includes example queries and explains that it replaces multiple sequential lookups, making usage context unmistakable.

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

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

Goes well beyond the annotations: discloses account/paid-plan requirements, latency (15-60s, thorough ~90s), the findings-packet return shape (verbatim evidence, confidence, source, fetched_at, gaps[], contradictions[]), the 'never invented' policy, semantic excerpting behavior, and the citation_uri fetchability guarantee. This is rich, non-obvious behavioral context.

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

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

Dense but disciplined — nearly every clause earns its place: auth, source scope, decomposition, output fields, sibling routing, depth semantics, citation policy, and latency. It is front-loaded with the most decision-critical constraint (account required). The tail of caveats could be lightly trimmed, but nothing feels like filler.

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

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

With no output schema, the description compensates by describing the result packet in prose, covering auth prerequisites, latency, depth options, and explicit alternatives. An agent has everything needed to both select and invoke this tool correctly, including what to do when not signed in.

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 both parameters, so baseline is 3, but the description adds real nuance: depth's 'standard'/'thorough' behaviors are elaborated with hop and gap-recovery details, and question is explained as natural-language and explicitly tolerant of broad/multi-part queries with examples. This is additive rather than 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 'Grounded multi-source research across Pipeworx's 1494 STRUCTURED data sources' — a specific verb, resource, and output. It explicitly contrasts with open-web search and names the sibling it is not (ask_pipeworx), making selection 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?

Provides explicit when-to-use ('Best for broad/multi-part questions over structured data'), when-not-to-use ('For a single lookup use ask_pipeworx'; 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'), and an auth-based exclusion ('If you are not signed in, use ask_pipeworx instead'). The conditions are concrete and directly actionable.

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

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

Annotations already show it's read-only, idempotent, and non-destructive. The description adds that results include full schemas with examples ready to call, enhancing transparency beyond annotations.

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

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

The description is dense yet well-organized. It starts with the core purpose, lists examples, and ends with usage advice. 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?

Even without an output schema, the description fully explains what the tool returns: top-N tools with names, descriptions, and schemas. It covers input, output, and usage context completely.

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%. The description explains the main query parameter and its aliases, and the limit parameter with defaults, adding meaningful context beyond the schema.

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

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

The description clearly states that the tool finds tools by describing a data or task, listing many domains and indicating it returns relevant tools with schemas. It distinguishes itself from sibling research/query tools by being the meta-tool for discovery.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover' and 'Call this FIRST when you have many tools available'. Provides clear context and usage direction.

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 behavior. The description adds valuable context about data sources (SEC, XBRL, USPTO, news, GLEIF), fallback logic (GDELT→GNews), and a soft-fail condition for patents. No annotation 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 dense but well-structured, front-loading purpose with examples then listing sources and returns. Every sentence adds value, though slight length could be trimmed slightly for optimal 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 complexity and no output schema, the description covers the return fields and data sources comprehensively. It explains fallback behavior and sunset warnings. Minor gaps like response size or pagination do not detract significantly.

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 enriches parameter meaning: value accepts ticker or zero-padded CIK (with examples), and type restricts to 'company'. It also clarifies that names are unsupported.

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 US public companies. It provides specific query examples and distinguishes itself from chaining single-pack lookups, 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?

Explicitly instructs to prefer this tool over chaining lookups for holistic views and specifies that names are not supported, directing users to resolve_entity first. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description adds limited behavioral context beyond stating it deletes a memory. It does not contradict annotations.

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

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

Two efficient sentences, front-loaded with the action, no wasted words. 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 simple parameter, no output schema, and annotations covering safety and idempotency, the description is complete with usage context and tool pairing.

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 description 'Memory key to delete'. The description adds no additional meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

Description clearly states 'Delete a previously stored memory by key' which is a specific verb and resource. It also mentions tool companions 'remember' and 'recall', distinguishing it as 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 specifies when to use: when context is stale, task is done, or to clear sensitive data. Also suggests pairing with remember and recall, providing clear context for use.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by explaining the process: fetching the page, extracting title/description/key links, and emitting standard markdown format. It also notes the output is a 'single text blob' for easy deployment, which provides useful context beyond annotations.

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

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

The description is front-loaded with the main purpose and process in the first sentence. It is a single paragraph with no redundant phrases, efficiently covering purpose, process, and use cases. Slightly longer than necessary but still 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?

For a simple tool with two parameters and no output schema, the description covers what the tool does, how it works, output format, and use cases. It lacks details about error handling or rate limits, but annotations and simplicity make it fairly 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%, so the description does not need to add much parameter detail. It mentions 'any URL' and implies the URL is the target, matching the schema. For 'max_links', the description only refers to 'key links' indirectly; it does not explain the default or maximum, so no added 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 generates a 'production-ready llms.txt file' for any URL, specifying the exact resource and action. It also mentions the purpose for AI crawlers like ChatGPT, Claude, and Perplexity, distinguishing it from sibling tools like 'scan_competitor_ai_presence' by focusing on file generation rather than scanning.

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

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

The description provides explicit use cases: indexing a client's site, drafting for own project, or auditing a competitor. This offers clear context for when to use the tool. However, it does not directly compare to siblings or state when not to use it, slightly reducing the score.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds return fields and purpose but no extra behavioral traits like pagination limits. Adequate given 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 action and outputs, second gives usage guidance. No wasted words.

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

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

For a simple tool with one optional parameter, the description covers return fields and usage. Lacks mention of pagination or default filtering, but complexity is low.

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; description does not add meaning beyond what the schema's description of 'include_inactive' already provides.

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

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

Clearly states it lists subscriptions and specifies the returned fields. Differentiates from siblings like subscribe and unsubscribe by naming them in usage guidance.

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

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

Explicitly tells when to use: 'review what you're monitoring before adding more or to find an id to cancel.' Does not explicitly state when not to use, but context implies it's for listing active subscriptions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the description does not need to repeat safety. It adds value by explaining returned data includes resource IDs for use with montgomery_query, clarifying the output's purpose. 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, zero fluff. Front-loaded with purpose and action. Every word is necessary.

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

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

For a search tool with thorough annotations and full schema coverage, the description is complete. It explains output (dataset names, descriptions, IDs) and connects to a sibling tool. No gaps given the tool's straightforward nature.

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 4 parameters. The description adds context: query is the search term, limit and offset for paging, _apiKey is optional. This goes beyond the schema by explaining the return format in relation to parameters.

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

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

The description clearly states it searches the Montgomery County open-data catalogue by keyword, returns dataset names, descriptions, and Socrata resource IDs. This distinguishes it from siblings like montgomery_query (which queries a specific dataset) and montgomery_recent (recent datasets).

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

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

Description explicitly mentions use with montgomery_query, providing a clear workflow. It implies the purpose (search before query), but does not list when not to use or alternatives. Sibling context shows other dataset tools, but no explicit exclusions.

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

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

Annotations indicate readonly, open-world, idempotent, and non-destructive behavior. The description adds that it runs raw SoQL queries with full clause support, mentions optional _apiKey for higher rate limits, and notes a default/max limit of 5000. 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 extremely concise: two sentences that front-load the action and provide essential context without any wasted words.

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

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

Given the tool has 8 parameters, no output schema, but rich annotations, the description sufficiently covers the tool's purpose, how to find resource IDs, supported SoQL clauses, and rate limit considerations. It is complete for an AI agent to invoke correctly.

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

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

With 100% schema description coverage, the schema already describes all parameters. The description adds value by explaining _apiKey's purpose (rate limits) and default/max for limit, but does not significantly augment the schema beyond that. Baseline 3 is appropriate.

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

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

The description clearly states the tool runs a raw SoQL query against Montgomery County open-data resources, identifies the specific resource using Socrata IDs, and distinguishes from sibling tools like montgomery_datasets and montgomery_recent.

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 directs users to montgomery_datasets to find a resource ID or montgomery_recent for common ones, providing clear guidance on when to use alternatives. It does not state when not to use this tool, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds behavioral details: returns latest rows newest-first, can filter with SoQL where. No contradictions. Could mention pagination or rate limits, but given annotations cover safety, the added context is sufficient.

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

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

Compact with three sentences; front-loaded with core function. Every sentence is informative with no redundancy. Uses bold for key instructions and examples in schema.

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

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

Given no output schema, the description explains return order. Covers dataset names, filtering, usage guidance, and sibling tool reference. Complete for a simple retrieval 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 descriptions cover 100% of parameters. Description adds value by listing the dataset names explicitly (311, crime, permits) and explaining the SoQL where usage. This helps the agent understand the enum values and filtering capability beyond the schema.

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

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

Description clearly states the tool retrieves recent records from Montgomery County open datasets by friendly name, and distinguishes from montgomery_query. It specifies exactly which datasets are available (311, crime, permits) and the default behavior (newest-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 says 'PREFER OVER WEB SEARCH' for specific types of queries and provides alternatives: 'for anything else use montgomery_query'. Also advises when to add a SoQL where clause.

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 all false, so description carries full burden. It discloses rate-limiting ('Rate-limited to 5 per identifier per day'), the free/no-quota nature, and the claim_token workflow (anonymous filing returns a token that can later be passed to check status). These are valuable behavioral traits beyond any structured annotation.

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 minimal but every sentence adds distinct information: purpose, usage, exclusions, token flow, rate limits, and roadmap impact. It is front-loaded with the primary verb and structured logically from general to specific.

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

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

For a tool with no output schema, the description adequately explains the return behavior (claim_token, later status). It covers edge cases (different MCP server, no account), practical limits (rate limit, quota), and content guidelines. Nothing important appears missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds real value by showing the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and emphasizing message specificity ('which tool, what error, what data was missing'). It doesn't redundantly restate schema descriptions.

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

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

The description opens with a clear verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist,' and further enumerates the feedback types (bug, feature, data_gap, praise). It unambiguously distinguishes this tool from all siblings, which are research/monitoring tools, not feedback submission.

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 a tool returns wrong/stale data...', 'when a tool you wish existed isn't in the catalog...') and provides a clear exclusion: if the tool is from another MCP server, file with that server instead. It also advises what to include ('Describe the issue in terms of Pipeworx tools/packs') and what not to paste.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context: self-aggregating signal from CF analytics-engine, no PII, caching policy (5min-1h), and data structure (pack, tool, count). 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 appropriately sized, using bullet points for use cases. It is front-loaded with the core purpose and provides essential details without unnecessary fluff. Could be slightly more concise but is effective.

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

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

Given a single optional parameter and no output schema, the description covers the input behavior, use cases, and data sources. It explains what outputs to expect (top tools, packs, count) and the caching behavior, which is adequate for a trending tool.

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

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

The input schema covers the parameter 'window' with full description and enum values. The description adds semantic meaning by explaining how shorter windows surface hot trends and longer windows show steady-state demand, complementing 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?

Clearly states it returns top tools, top packs, and total call volume over a recent window. The description uses specific verbs and resources, and distinguishes itself from sibling tools like 'discover_tools' or 'search_within' by focusing on trending data derived from analytics.

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 three explicit use cases: discovering hot data sources, confirming popular tools, and checking alignment with agent needs. While it doesn't explicitly state when not to use it, the focused purpose makes usage scenarios clear.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds significant behavioral detail: walks child markets, date/threshold checks, partition sum near 1, Jaccard similarity filter, placeholder filter, fill check against live CLOB depth. 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?

Packed with information but somewhat dense. Front-loads basic functionality then details. Could be slightly more structured, but every sentence adds value.

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

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

Covers return format (opportunities array, partition_check object) and fill check behavior. No output schema but description explains fields like gap_pp, suggested_trade. Adequate for complexity, but could formalize return structure.

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

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

Schema coverage 100%, description adds extensive meaning: explains event as single-event mode with slug example, topic as cross-event mode with seed question and underlying mechanics (Jaccard, partition filter). Goes well beyond basic schema descriptions.

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

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

Clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks. Distinguishes modes (no args, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Provides explicit when-to-use for each mode (no args for trending scan, event for specific market, topic for cross-event). References polymarket_fill_risk for custom sizing. Could be more explicit about when not to use this tool, but still clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint. Description adds extensive behavioral details: caching behavior (1h KV, keyed on all knobs), response structure with segments, diagnostics for empty results, model families with formulas, and caveat on Fed data. Exceeds annotation scope significantly.

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

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

Long but well-structured: starts with purpose, then details model families, response shape, diagnostics, and knobs. Every sentence adds value, though density may challenge quick parsing. Could be slightly more streamlined but remains effective.

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

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

No output schema provided, but description fully explains response structure (by_segment, fed_candidates, diagnostics) and key fields (edge_pp_net, Kelly fractions, liquidity, spread). Covers edge computation, filter knobs, and caching. Complete given complexity.

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

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

Schema descriptions cover all 9 parameters fully (100% coverage). The tool description adds contextual value by explaining interaction effects (e.g., min_partition_leg_kelly vs min_kelly) and practical usage tips (e.g., slippage assumptions). One point above baseline due to rich context not present in 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?

Clear verb ('Scan') and resource ('Polymarket markets') with distinctive outcome ('return opportunities where Pipeworx data disagrees with market price'). Explicitly marketed for the 'what should I bet on today' use case, distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker that focus on specific aspects.

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 context for use ('exploit disagreements', 'discover opportunities') and includes tradeable-edge knobs and filters. Does not explicitly contrast with siblings but clearly defines scope (Fed bets noted as excluded from ranking). Sufficient for an agent to decide when to invoke.

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 explains the tool's behavior, including the response structure (tracked, expired, snapshot_dates), computation of decay metrics, data source (daily snapshots), and limits (60-day TTL). This goes well beyond the annotations which only indicate read-only, idempotent, and non-destructive behavior.

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

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

The description is structured with a clear purpose, then detailed output breakdown, and finally limitations. It is front-loaded with the key question. However, it is somewhat lengthy and could be slightly more concise without losing value.

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

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

Given no output schema, the description sufficiently explains the return fields and their meanings. It covers edge time-series, trends, decay, expiration, and snapshot dates. Some finer details (e.g., exact fields in tracked objects) are omitted but not critical.

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

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

The input schema covers both parameters with descriptions, and the description adds clarifying details like default values and constraints (max 30 days for days, default window '1wk'). This adds modest value beyond the schema.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific question. It distinguishes itself from the sibling 'polymarket_edges' by focusing on historical behavior rather than current edges.

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

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

The description explains when to use this tool (to evaluate edge longevity and shrinkage) and provides context on data limitations. However, it does not explicitly state when not to use it or name specific alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds beyond annotations by detailing behavioral traits: walks the ladder, returns specific verdicts, and explains risks of partial fills. No contradictions.

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

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

Description is well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET). Front-loaded with purpose. Every sentence adds value; no wasted words.

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

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

Despite no output schema, the description enumerates returned fields in detail (top_of_book, vwap_fill_price, slippage_pp, etc.). Given tool complexity and parameter count, the description provides complete context for an agent to understand tool behavior and output.

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

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

Schema coverage is 100%, but the description adds meaning: explains default side behavior for basket mode ('auto — sell if partition sum > 1, buy if < 1'), clarifies size_usd interpretation for both modes, and provides context for market vs event parameters.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes between single-market and basket modes with specific verbs and outputs. Sibling tools like polymarket_arbitrage and polymarket_edges are differentiated.

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

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

Explicitly instructs to use this tool 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains why: 'theoretical overround on thin books is not capturable, and partial basket fills convert an arb into an unhedged directional position'.

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

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

The description goes far beyond the readOnly/idempotent annotations by detailing response flags such as event_subject_mismatch, temporal_mismatch, and non_equivalent_bet_shapes, plus the NEVER-paired rule for unknown metric types. It also discloses the limitation that premapped pairings are matched by keyword overlap rather than a shared resolution source, which is valuable behavioral context.

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

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

The description is long but front-loaded with the core concept, then modes, then response details, and nearly every sentence carries meaningful information. It is denser than necessary and would benefit from clearer bullet structure, but it is appropriately detailed for a complex cross-venue comparison 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?

With no output schema, the description does a strong job of explaining return fields, flags, skipped counters, temporal alignment, and pairing caveats. It could be more explicit about what happens if neither a topic nor both explicit identifiers is supplied, since no parameters are required in the 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?

Although the input schema already documents all three parameters, the description adds crucial interaction semantics: topic shortcuts auto-fetch matching events on both venues, while explicit ticker/slug parameters override the topic-mapped side. This clarifies mode selection and how the parameters relate to each other.

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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question and explains when the delta is a real signal. It does not explicitly name or differentiate sibling tools such as polymarket_edges or polymarket_arbitrage, so it falls just short of a 5.

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

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

The description gives concrete guidance on when the spread is meaningful, noting that equivalent bet shapes produce a real signal while non-equivalent shapes are flagged. It also warns that most pre-mapped topics currently return compatibility_warning and that pre-mapped does not mean tradeable, which is strong practical guidance, though it does not explicitly mention alternative tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds scoping and pairing context beyond annotations, 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 concise sentences with perfect front-loading. 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?

Given 1 optional param, no output schema, and rich annotations, the description fully covers scope, behavior, and tool relationships.

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

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

Schema coverage 100% with parameter description. Description adds meaning: omission lists all keys, and provides practical examples.

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

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

Clear verb 'retrieve' or 'list' with specific resource 'value saved via remember' and 'all saved 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?

Explicitly states when to use: 'look up context the agent stored earlier'. Mentions alternative tools (remember, forget) and behavior when key is omitted.

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, destructiveHint. The description adds significant behavioral context: it specifies the returned fields, the effect of mark_read (flags events so next call shows only newer ones), and mentions the feed is persisted. This goes beyond annotations without contradiction.

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

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

The description is five sentences with a clear front-loaded purpose. Each sentence adds value: purpose, fields, filters and mark_read, side effect, alternative endpoint. No wasted words. Excellent structure.

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

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

Given the tool's low complexity (5 optional parameters, no output schema), the description covers all essential aspects: what it returns, filtering, side effects, and alternatives. It is complete enough for an agent to use correctly.

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

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

Schema coverage is 100% with all parameters described. The description adds behavioral context, e.g., mark_read 'flag returned events read so the next call only shows newer ones' and 'unread_only' explanation. This adds value beyond the schema, but the schema already does a good job, so a 4 is appropriate.

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

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

The description starts with 'Pull fired events from your subscription feed', clearly stating the verb (pull) and resource (fired events). It explains the specific fields returned (source, citation_uri, payload) and distinguishes itself by mentioning filtering and the mark_read side effect. It also notes an alternative REST endpoint, differentiating from siblings like list_subscriptions or subscribe.

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

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

The description provides clear context for when to use the tool: to retrieve recent alerts, with filtering options and mark_read functionality. It mentions that polling works fine and points to an alternative GET endpoint for scripts/dashboards. However, it does not explicitly state when NOT to use it or compare to sibling tools like recent_changes, which would make it a 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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: fan-out to multiple sources (SEC, GDELT/GNews, USPTO), fallback behavior (GDELT→GNews on errors), patent source deprecation note, and return structure (changes grouped by source, total_changes count, citation URIs). No contradictions.

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

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

The description is concise (3 sentences) while packing essential information. It is front-loaded with example queries, immediately clarifying the tool's purpose. No redundant or filler content; 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 absence of an output schema, the description adequately describes the return structure (changes grouped by source, total_changes count, citation URIs). It covers all aspects an agent needs: what data sources are queried, fallback behavior, parameter format, and alternative tool. Complete for a read-only information retrieval 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 all three parameters. The description adds practical usage guidance: explains the since parameter accepts ISO dates or relative syntax with examples ('7d', '30d', '3m', '1y') and recommends '30d' or '1m' for monitoring. This enriches the schema definitions.

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 ('change feed', 'fans out') and clearly identifies the resource (company changes over time). It provides example queries ('What's new with X?') and explicitly distinguishes from sibling tool entity_profile ('Use entity_profile instead when you want the static 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?

The description includes explicit when-to-use and when-not-to-use guidance: 'Use entity_profile instead when you want the static profile'. It also suggests typical window values ('Use "30d" or "1m" for typical monitoring'), helping the agent decide parameter values.

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=false (mutation), idempotentHint=true, destructiveHint=false. Description adds valuable behavioral details: persistence scoped by user identifier, 24-hour retention for anonymous sessions vs persistent for authenticated, and key-value pair storage. 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 concise (4 sentences) and front-loaded: first sentence states purpose, second gives usage guidance, third provides behavioral details, fourth references companion tools. Every sentence adds value with no redundancy or fluff.

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

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

For a simple 2-parameter tool with 100% schema coverage and no output schema, the description is complete. It covers purpose, when to use, behavioral characteristics (persistence, scoping), and connections to sibling tools. No missing information needed for correct invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds semantic value beyond schema by providing example keys like 'subject_property', 'target_ticker', 'user_preference', and clarifies what values can contain ('findings, addresses, preferences, notes'). This enriches the agent's understanding of how to fill parameters.

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

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

The description clearly states the tool saves data for reuse, with concrete examples like 'resolved ticker, target address, user preference, research subject'. It distinguishes from siblings recall and forget, which are mentioned as companion 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 guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' Also pairs with recall and forget, providing clear context for when to use this tool versus alternatives.

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

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

It discloses that unresolved identifiers are listed under `unresolved` rather than omitted, and that LEI/FIGI enrichment degrades gracefully if GLEIF/OpenFIGI is unavailable. This goes beyond the readOnly/idempotent annotations with actionable behavior.

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

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

The description is dense and front-loaded with the purpose and usage rule, but it delivers all details in a single paragraph. Some structured bullets would improve scannability, but no sentence is wasted.

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

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

Given the lack of an output schema, the description fully explains the return behavior (canonical identifiers, source labels, unresolved handling) and error tolerance (graceful degradation), making it complete for selecting and trusting this 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?

While the schema already covers parameters at 100%, the description explains what 'company' and 'drug' resolve to, including the cross-source identity spine and the specific identifier sources (SEC EDGAR, GLEIF, OpenFIGI, RxNorm), adding meaning beyond the schema's basic types.

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 'resolve' and the resource 'a user-spoken NAME to canonical/official identifiers,' with concrete example queries. It distinguishes the tool from siblings by emphasizing it provides identifiers other tools require as input.

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID,' giving a clear when-to-use. It does not name alternatives or explicitly say when not to use, but the context is clear.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive. Description adds that it internally calls ai_visibility_check, ranks results, and returns score, confidence, signal density. No contradictions; additional behavioral detail 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?

Four sentences: purpose, process, use case, output. No redundant words, front-loaded with key action. Every sentence earns its place.

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

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

For a tool with 4 parameters, no output schema, and many siblings, the description covers what, when, parameters, output fields, and internal mechanism. No gaps remain.

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

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

Schema coverage is 100%, but description adds significant meaning: entities array has size limits and first-is-subject; models explains defaults and conditional requirements; context gives examples; _apiKey explains condition and destination. Baseline 3 exceeded by far.

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 compares AI visibility across multiple entities side-by-side, probing each and ranking them. This distinguishes it from siblings like ai_visibility_check (single entity) and compare_entities (general comparison). The verb 'Compare' and resource 'AI visibility' are specific.

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

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

Explicitly says it is useful for competitive AI-marketing audits and gives an example question. However, it does not explicitly state when not to use it or name alternatives (e.g., use ai_visibility_check for single entity). Still, 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds key behaviors: it calls external services, has timing considerations (5-30s for bundlephobia), and handles partial failures gracefully with a sources_failed field.

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 largely concise and front-loaded with the main purpose, but includes several details that could be streamlined slightly without losing 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?

Despite no output schema, the description thoroughly explains the return structure (summary block fields, per-advisory details, links, alternative versions) and partial failure behavior, making it complete for agent understanding.

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

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

Schema covers both parameters with descriptions (100% coverage). The description adds practical nuance: 'Scoped packages (e.g. "@types/node") are accepted', which is not in the schema description.

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

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

The description clearly states the composite check for deciding whether to add an npm package, specifying it fans out across deps.dev and bundlephobia and returns a detailed summary. It distinguishes from siblings as no other tool does dependency scanning.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small"' and notes NPM-only with alternatives for other ecosystems. However, it does not name the exact alternative tool, slightly reducing 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?

Beyond annotations (readOnly, idempotent), the description reveals embedding model (BGE-base-en), window size (500-char overlapping), similarity metric (cosine), 200K char cap with truncation flag, and output passaging structure. No contradiction with annotations.

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

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

Six sentences, front-loaded with purpose, each sentence adds new information (use case, pairing, technical details). No fluff, highly efficient.

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

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

Covers all essential aspects: input format, output structure (offsets, scores), limitations (cap, truncation), relationship with sibling tool, and specific model details. Despite no output schema, description sufficiently explains return values.

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

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

Schema covers 100% of parameters with descriptions. The description adds context: examples for query, clarification on text input (e.g., fetched record), and limit default/range, enhancing understanding beyond schema.

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

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

The description clearly states it performs semantic search inside a fetched record, specifying inputs (text and query) and outputs (top passages with offsets and scores). It distinguishes itself from siblings like ask_pipeworx_grounded by explicitly pairing with it.

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

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

Describes when to use: when the record is too big to fit in the prompt. It also mentions pairing with ask_pipeworx_grounded for grounding, but lacks explicit exclusions or alternatives for other scenarios.

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 extensive behavioral context beyond annotations: requires account type, details on supported event types, delivery channels (feed always on, optional email/SMS/webhook with constraints like SMS 10/day cap and webhook auto-disable after failures). 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 front-loaded with the core purpose and return value, then efficiently covers types, params, and delivery in a structured manner. 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?

Given the tool's complexity (multiple event types, delivery channels), the description covers prerequisites, type-specific parameters, delivery behavior, and constraints. No output schema exists, but the return value (subscription id) is mentioned. The description is sufficiently complete for correct invocation.

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

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

Despite 100% schema coverage, the description enriches parameter understanding with concrete examples and constraints for each type's params and delivery options. It goes beyond schema descriptions to clarify usage patterns.

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 'Create a proactive monitoring subscription to a live-data event stream' and 'Returns the new subscription id', clearly identifying the action and result. It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description clarifies prerequisites (requires Pipeworx OAuth account) and supported types, but does not explicitly state when to use this tool versus alternatives. The context of subscription creation is evident, but lack of explicit when-not or alternative references prevents a 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful behavioral context: that results are drawn from a live catalog, and the return format (category-bucketed with tool+argument shape). No contradictions.

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

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

The description is front-loaded with alternative question phrasings, which helps the agent recognize intents. It is somewhat verbose but every sentence adds value. No wasted words.

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

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

For a simple tool with one optional parameter and no output schema, the description thoroughly explains purpose, usage, and what to expect. It covers all necessary context for an agent to invoke it correctly.

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

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

Schema coverage is 100% with description for the only optional parameter. The description adds value by explaining the effect of omitting vs. passing the topic parameter, with example values. This goes beyond the schema's generic 'Optional focus area'.

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 category-bucketed example questions for onboarding. It uses specific verbs like 'returns' and resources like 'example questions', and distinguishes from siblings like ask_pipeworx and discover_tools.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Provides guidance on when to omit vs. pass the topic parameter. Lacks explicit when-not-to-use, 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?

Discloses that the row is deactivated, not deleted, and that historical events remain accessible via recent_alerts. This adds context beyond annotations, which already indicate idempotent and non-destructive behavior.

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

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

Two concise sentences front-loaded with the action. Every sentence adds value with no unnecessary words.

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

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

For a simple tool with one required parameter and no output schema, the description fully covers purpose, ownership constraint, and the deactivation behavior with reference to related tools.

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

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

Schema coverage is 100% with a clear description of the 'id' parameter. The tool description mentions 'by id' but does not significantly add meaning beyond the schema's parameter description.

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

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

Clearly states the action ('Cancel a subscription by id') and the resource (subscription). Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying cancellation.

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

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

Provides a key usage condition: 'Ownership is enforced — you can only cancel your own subscriptions.' This helps the agent decide when to use the tool. Could mention when not to use, but sufficient for a simple tool.

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

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

Beyond the readOnly/idempotent/openWorld annotations, the description discloses critical behavior: the two-path execution (SEC EDGAR vs grounded pipeline), the meaning of each verdict type, and the crucial caveat that could_not_verify is not evidence. It also states the tool verifies with verbatim evidence and citations, adding substantial context not present in annotations.

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

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

The description is front-loaded with trigger phrases and a clear purpose, then structured into routing behavior, return values, and caller warnings. Every sentence provides necessary operational detail—no filler. The 'IMPORTANT for callers' section is efficiently integrated.

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

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

Without an output schema, the description fully compensates by enumerating verdict types, explaining the difference between could_not_verify and unsupported, and mentioning the citation and reasoning included in results. It also covers the tool's role in replacing multi-step pipelines, making it self-sufficient for an agent.

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

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

Schema coverage is 100% and both parameters are well-described. The description adds extra meaning for tolerance_pct by explaining that it overrides the default implied by wording and giving a specific use case (hallucination detection with 1-2%). Claim receives concrete examples, reinforcing the schema.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with trigger phrases like 'fact check' and 'verify the claim that'. It distinguishes itself from siblings by highlighting the SEC EDGAR fast path for company-financial claims and fallback to the grounded pipeline, and by explicitly noting it replaces 4-6 sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and clarifies the routing behavior for company-financial vs other claims. It also explains important callers' semantics for could_not_verify and unsupported, guiding when to trust the result and when not to.

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