Arcgis Sarasota

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

Annotations already indicate read-only and idempotent behavior. Description adds critical behavioral details: default free model (Workers AI Llama-3.3-70b), the need for an API key to probe Anthropic with cost implications, and the return structure (per-model score, confidence, signals, raw_response plus combined view). 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?

Five sentences, each with a distinct purpose: core action, default model + cost, return format, use cases. No redundancy, front-loaded with main purpose. 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?

Despite having no output schema, the description adequately explains the return value structure. All 4 parameters are covered, required parameter is clear, and the tool's behavior is fully described for its complexity level.

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

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

Schema coverage is 100% so baseline is 3. Description enriches semantics with examples ('Pipeworx', 'OpenInvoice'), explains when to use context for disambiguation, and clarifies the _apiKey purpose (passed through to Anthropic). Adds value beyond schema descriptions.

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

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

Clearly states the action 'Probe' and the resource 'LLMs', specifies the output 'score visibility (0-100) per model', and distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on per-model scoring and default free model.

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 mentions use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Provides clear context for when to use, but does not explicitly state when not to use or compare to alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description doesn't need to repeat safety traits. It adds valuable behavioral context: fills arguments, routes to the right tool, returns stable pipeworx:// citation URIs, works on every tier, and handles news via live feeds. No contradictions with annotations, and the description goes beyond them with operational details.

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

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

The description is front-loaded with 'PREFER OVER WEB SEARCH' and delivers maximum utility per sentence: use cases, examples, routing behavior, escalation paths, and news handling. Though lengthy, every sentence earns its place and there's no redundancy or vague 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?

Given the tool's complexity as a routing gateway to thousands of sources, the description is remarkably complete. It covers what it does, when to use it, when not to use it, examples, output characteristics (structured answer with citation URIs), and tier/performance notes. No output schema exists, but the description adequately describes return value.

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

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

The input schema has 100% coverage: 'question' is described as natural language with aliases (query, q, prompt, text, input). The tool description explains that the question is routed and arguments are filled automatically, but adds no extra parameter-level semantics beyond the schema. Baseline 3 is appropriate since schema does the heavy lifting.

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

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

The description states a specific verb+resource: it routes questions to one of 5,529 tools across 1,455 verified sources and returns structured answers with citation URIs. It clearly differentiates from siblings by explicitly naming ask_pipeworx_grounded and deep_research as step-up alternatives.

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

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

Provides explicit when-to-use guidance: prefer over web search for factual questions about real-world entities, events, or numbers, with example queries. Also gives exclusion criteria: use ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad multi-part questions, and notes breaking-news handling.

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 the tool as read-only, open-world, and idempotent. The description adds valuable context: it is a full working router with no fallback, currently matches ask_pipeworx exactly because no candidate is active, and the last candidate was retired on a specific date. This goes well beyond the annotations by explaining the experimental state and comparison 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 three sentences and every sentence provides distinct value: current status, usage direction, and the nature of the router. It is front-loaded with the most important context and contains no filler or redundant information.

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

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

For a complex router with thousands of tools, the description covers the key aspects: what it is, its relationship to ask_pipeworx, current behavior, and how to use it. There is no output schema, but the description sufficiently informs an agent about invocation and expected behavior.

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

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

Schema coverage is 100%, with all parameters (question and its aliases) documented in the schema. The description only mentions 'same arguments' without adding any new meaning about parameter formats or usage, so it does not exceed the baseline of 3.

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

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

The description clearly states it is a beta version of ask_pipeworx, a universal router, and differentiates it from the stable sibling by mentioning candidate routing improvements and current state. This gives a specific verb ('ask') and resource ('Pipeworx router') while distinguishing it from similar tools.

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

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

The description explicitly states to use it exactly like ask_pipeworx when wanting the newest routing, and mentions that results are compared against the stable router. This provides direct usage guidance and names an alternative, satisfying the when-to-use requirement.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints, but the description adds critical behavioral detail: same routing as ask_pipeworx, answer extracted only from tool result, structured refusal reasons, and the extra LLM call cost. No contradiction with annotations.

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

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

The description is content-dense but slightly long, with every clause contributing value. It front-loads the core purpose and then covers mechanism, return format, usage, and tradeoffs. The inclusion of exact source counts (5,529 across 1455) is a minor extra that adds context but could be trimmed.

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 explicitly enumerates the success return fields and all refusal reasons, making the response contract clear. It also addresses cost tradeoffs and high-stakes use cases, making it complete for a tool of this complexity.

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

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

Schema coverage is 100%, with all parameters described as aliases for 'question.' The description does not add parameter-specific semantics beyond emphasizing the natural language question context, but the schema carries the burden, so a baseline of 3 is appropriate.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' clearly stating the tool's function as a grounded Q&A mode. It distinguishes itself from the sibling ask_pipeworx by specifying the extraction step and explicit refusal behavior, making sibling differentiation strong.

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 is provided: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and 'prefer ask_pipeworx for casual lookups.' This directly addresses when to use and when not to use, including a named alternative.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details: safety mechanisms (low-confidence matches suppress analysis, closed markets skip fan-out), response shapes, resolver contract, parent event extraction, news fallback fields, and resolution-rule risk. This far exceeds annotation requirements.

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

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

The description is very long and detailed, covering classifiers, fan-out examples, response shapes, resolver contract, and safety mechanisms. While front-loaded with purpose, it reads more like a reference manual. Some detail is necessary due to complexity, but it could be more structured (e.g., separate sections) and concise.

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

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

Given the tool's complexity and absence of output schema, the description is exceptionally complete. It covers input format, resolution behavior, safety mechanisms, response fields, and edge cases (closed markets, wide spreads, resolution rules). Almost no gaps remain for an agent to interpret expected behavior.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning beyond schema: it explains the market parameter accept slug, URL, or question text (already in schema, but reinforced), provides examples of fan-out for different classifiers, and clarifies the depth and include_raw parameters with practical guidance. This adds meaningful context.

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

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

The description clearly states the tool's purpose: research a Polymarket bet by pulling Pipeworx data. It specifies inputs (slug, URL, question text) and outputs (evidence packet + comparison). However, it does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_arbitrage, though the purpose is distinct enough.

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 use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It gives examples but does not explicitly state when not to use the tool or mention alternatives. Usage guidelines are practical but lack exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds rich behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradictions with annotations.

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

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

The description is front-loaded with natural language examples and uses a clear structure. It is somewhat lengthy but every sentence adds value. Could be slightly more compact, but it is well-organized and efficient.

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

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

Given the annotations and schema, the description provides all necessary context: data sources, entity types, metric details, sorting, citation URIs, and performance benefit compared to alternatives. No output schema, but return values are adequately described. This is complete for an agent to select and 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?

Schema coverage is 100% with good descriptions. The description adds significant value beyond the schema: explains what data is pulled for each type (e.g., 'LATEST 10-K revenue + net income + cash + long-term debt' for companies), concrete examples for values, and behavior like handling tickers and CIKs. This justifies a 4.

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

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

The description starts with concrete example phrases and states the tool performs side-by-side comparison of 2-5 companies or drugs in a single parallel call. It clearly distinguishes from siblings by stating it replaces 8-15 sequential lookups, which is a strong behavioral differentiator.

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.' This gives clear when-to-use guidance and implies alternatives (entity_profile for single lookups). It leaves little ambiguity for an agent.

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/openWorld/idempotent annotations, the description discloses parallel tool routing, output packet fields (gaps[], contradictions[], citation_uri), a two-hop iteration behavior by depth, semantic excerpting, latency expectations, and the paid-plan requirement for 'thorough'. No contradictions with annotations.

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

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

The description is a dense single paragraph, front-loaded with the account caveat and core purpose, but it packs a lot of detail (depth semantics, return format, timing) into one block. While every sentence adds value, structure could be improved with bullet points, so it's slightly above average but not exemplary.

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 covers the return value format: findings with evidence/confidence/source/fetched_at/citation, gaps[], contradictions[], hop and citation_uri, plus depth-specific behavior, latency, and account constraints. No gaps in necessary context 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?

The input schema already fully describes both parameters (100% coverage), so baseline is 3. The description adds operational meaning by tying depth values to facet counts and hop behavior (gap recovery, lead chasing) and stating 'thorough' requires a paid plan, which is 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 performs grounded multi-source research across Pipeworx's structured data sources, decomposing questions and returning a findings packet. It explicitly contrasts with open-web search and differentiates from sibling ask_pipeworx for single lookups, making its purpose and scope unambiguous.

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

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

The description gives explicit when/when-not guidance: use for broad/multi-part structured-data questions, use ask_pipeworx for single lookups or breaking/colloquial current news. It also states account requirements and a fallback if not signed in, so an agent can make an informed selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by detailing the return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly'. No contradiction.

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

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

The description is three sentences, front-loading the purpose and then listing domains and return behavior. It is informative without excessive length, though slightly verbose in the domain list.

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

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

Given the tool's simplicity (6 params, no nested objects, no output schema), the description fully explains the return values and usage context, making it self-contained for an agent to decide when to call.

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 does not add new parameter-level details beyond what the schema provides, but it provides example queries in the schema 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?

The description explicitly uses the verb 'Find' with the resource 'tools', and lists specific domains (SEC filings, financials, etc.), clearly distinguishing this discovery tool from sibling tools that perform specific tasks.

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

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

The description advises 'Call this FIRST when you have many tools available and want to see the option set', providing clear when-to-use guidance. It implicitly indicates alternatives by stating use when you need to browse, but lacks explicit when-not-to-use or alternative tool names.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds valuable behavioral context: it fans out across multiple sources, lists exact data returned, notes that patents soft-fails due to USPTO API sunset, and describes fallback chains (GDELT→GNews). 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 detailed but well-structured: it opens with example queries, then explains the tool's behavior, return fields, and limitations. Each sentence serves a purpose. However, it could be slightly more terse; some details (like the exact fields returned) are listed in a dense paragraph that might be hard to scan quickly.

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

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

Given there is no output schema, the description fully explains what the tool returns (cik, company_name, recent_filings up to 5 with URIs, fundamentals, patents, news, LEI). It also covers supported entities (US public companies), input formats (ticker or CIK), and limitations (patents soft-fail, name not supported). This is comprehensive for an agent to understand the tool's capabilities and constraints.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds important nuance that the 'value' parameter accepts ticker or zero-padded CIK and explicitly says names are not supported, which goes beyond the schema's generic description. It also clarifies that 'type' only supports 'company', matching the enum in the schema.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' and gives multiple example queries. It distinguishes from sibling 'resolve_entity' by noting that names are not supported and that tool should be used first if only a name is available.

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 prefer this tool: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also provides clear when-not: 'names not supported (use resolve_entity first if you only have a name).'

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds minimal extra beyond confirming deletion and mentioning sensitive data clearing. No contradiction.

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

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

Two sentences, front-loads purpose, no wasted words. Appropriate length for a simple tool.

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

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

Given simple tool (1 param, no output schema, good annotations), description is complete: explains purpose, usage, pairing with siblings. No gaps detected.

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

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

Schema coverage is 100% for the single parameter 'key', with schema description 'Memory key to delete'. Description does not add further meaning beyond 'by key'. Meets baseline but no extra value.

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

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

The description clearly states the tool deletes a previously stored memory by key, using specific verb 'delete' and resource 'memory'. It distinguishes from siblings by mentioning pairing with 'remember' and 'recall'.

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

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

Provides explicit conditions for use (stale context, task done, clear sensitive data) and suggests pairing with siblings. Lacks explicit when-not scenarios, but sufficient context given tool simplicity.

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 (safe read), idempotentHint (same result on repeat), and destructiveHint=false. The description adds that the tool fetches the page (network call) and extracts title/description/key links, which are beyond the annotations but do not contradict them. No mention of error handling or limits beyond the max_links parameter.

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

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

The description is three sentences long with no fluff. The first sentence immediately states the core purpose, followed by a brief process summary, and a bullet-like list of use cases. Every sentence serves a purpose.

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

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

Given the simple tool with only two parameters (100% coverage) and strong annotations, the description is complete. It explains the output format (single text blob in standard llms.txt markdown) even though no output schema exists, and the use cases are well covered.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (url and max_links) with descriptions. The description repeats the default and max for max_links but adds no new semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: generating a production-ready llms.txt file for any URL. It specifies the verb (generate), resource (llms.txt), and scope (any URL), distinguishing it from sibling tools like deep_research or scan_competitor_ai_presence.

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

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

The description lists explicit use cases (getting a client's site indexed, drafting for own project, auditing competitor), but does not provide when-not-to-use guidance or explicitly name alternatives. However, the use cases are clear and cover common 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the description's extra detail about returned items adds some value but does not disclose further behavioral traits such as error handling or rate limits.

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

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

A single, well-structured sentence that communicates the tool's purpose efficiently with no extraneous information.

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

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

For a simple read-only tool with one parameter, the description covers what the tool does and what it returns. It does not address error scenarios or output schema, but annotations compensate for safety. Slightly incomplete for edge cases.

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

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

Schema coverage is 100% and the description adds little beyond the input schema's parameter description. The tool description mentions 'by url' and gives an example, but the schema already provides a clear description and example.

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 verb 'Get', the resource 'ArcGIS Feature/Map Service layer's schema', and lists specific outputs: fields, geometry type, record count, and capabilities. Distinguishes from sibling 'query_layer' which likely queries data rather than schema.

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

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

The description implies usage for retrieving schema metadata but does not explicitly mention when to use this tool versus alternatives like 'query_layer'. No exclusion or prerequisite guidance is provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds context about return fields and the include_inactive parameter, complementing 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?

Two concise sentences: first defines purpose and output, second provides usage guidance. No extraneous 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 rich annotations, full schema coverage, and a simple read-only operation, the description fully covers what an agent needs without missing 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?

Schema coverage is 100%, and the description does not add additional meaning beyond what the schema provides for the single boolean parameter.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly advises when to use: 'before adding more' and 'to find an id to cancel', providing clear context and alternatives.

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

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

Despite all-false annotations, the description discloses rate limiting ('Rate-limited to 5 per identifier per day'), quota impact ('doesn't count against your tool-call quota'), and the asynchronous claim_token mechanism. It also adds content rules ('don't paste the end-user's prompt'), all without contradicting the annotations.

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

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

The description is long but every sentence carries distinct, necessary information: purpose, use cases, scope restriction, content rules, token flow, rate limit, and quota. It is front-loaded with the core purpose and remains well-structured and scannable 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?

With no output schema and all-false annotations, the description fully compensates by covering both filing and checking modes, rate limits, quota behavior, and strict tool-scoping guidance. Combined with a rich parameter schema, the tool is thoroughly documented for autonomous selection and invocation.

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

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

Schema coverage is 100%, giving a baseline of 3, but the description adds significant extra semantics: instructing that message content be framed around Pipeworx tools/packs rather than user prompts, and illustrating the exact claim_token usage pattern with a code-like example. This goes well beyond the schema descriptions.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which clearly states the verb and resource. It distinguishes itself from sibling tools by enumerating specific use cases (bug, feature, data_gap, praise) and by scoping feedback to Pipeworx tools only, unlike ask_pipeworx or 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?

Provides explicit when-to-use triggers such as 'when a tool returns wrong/stale data' and clear exclusions: 'if the tool came from a different MCP server... file it with that server instead.' It also explains the two modes—filing feedback and following up via claim_token—with no ambiguity.

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

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

Annotations already cover safety (readOnly, idempotent, not destructive). The description adds valuable context: it's self-aggregating from CF analytics, no PII, and caching behavior (5min-1h). This explains what happens beyond the annotation hints.

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

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

Front-loaded with a clear purpose, followed by bullet-point use cases, then technical details. Every sentence adds value with no redundancy. Appropriate length for the information conveyed.

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 input (one optional parameter with enum) and no output schema, the description covers everything: purpose, usage scenarios, caching, and data derivation. No gaps.

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

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

Schema coverage is 100% and the parameter description already explains window options and their meaning. The main description reinforces this, adding context about 'hot right now' vs 'steady-state'. No additional syntax needed.

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 first sentence clearly states it returns trending tools, packs, and call volume. It specifies the resource and action, and the three use cases further clarify its purpose. It distinguishes from sibling tools like discover_tools by focusing on current trends.

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

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

Explicitly lists three specific use cases (discovering hot sources, confirming canonical tools, aligning usage). Provides clear guidance on when to use it, making it easy for an agent to decide.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds context: scans top ~200 markets, uses Jaccard similarity ≥0.30, partition filter drops placeholders, returns opportunities with specific fields, includes fill check. 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 information-dense and structured with clear sections, but somewhat verbose with technical details like Jaccard threshold and specific response fields. Could be more concise while maintaining clarity.

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

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

Very complete given complexity: covers all modes, filters, return values, and links to related tool polymarket_fill_risk. No output schema but description explains response shape adequately.

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

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

Schema coverage is 100% with descriptions for both parameters. Description enhances meaning: explains event slug/URL usage, topic seed question, and behavioral differences between modes. Adds value beyond schema.

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

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

Description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes: no args (trending_scan), event (per-event), topic (cross-event). Specific verb+resource, differentiates from siblings like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance on when to use each mode: 'Call with NO args for a trending_scan... pass event for... or topic for...' Recommends event mode for a specific market and explains cross-event mode catches patterns missed by single-event. Lacks explicit 'when not to use' but is clear.

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

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

The description extensively details internal logic (model families, edge calculation, Kelly sizing, slippage), caching behavior (1h KV-level), and response structure, going well beyond the annotations (readOnlyHint, etc.). No contradiction with annotations.

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

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

The description is detailed and well-structured, starting with purpose, then models, knobs, and response. However, it is quite lengthy, and while every sentence adds value, it could be more concise for an AI agent scanning for quick understanding.

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

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

Given the complexity (9 parameters, multiple model families, edge/Kelly calculations, no output schema), the description fully explains the response structure (by_segment, fed_candidates, _diagnostics) and internal logic, ensuring agents understand what to expect and how to interpret results.

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

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

Input schema covers all 9 parameters with descriptions (100% coverage). The description adds significant extra context, such as explaining the interplay between min_kelly and min_partition_leg_kelly, and providing usage guidance for knobs like max_spread_pp and min_liquidity.

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 scans Polymarket markets for discrepancies between Pipeworx data and market price, targeting 'what should I bet on today' use case. However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, slightly reducing clarity.

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

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

The description implies the tool is for discovering betting opportunities without paging, and mentions knobs for filtering, but does not explicitly state when to use this tool versus alternatives (e.g., polymarket_arbitrage for pure arbitrage).

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 the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it reads from daily snapshots, has a 60-day TTL, and computes decay from daily closes (not intraday). This goes beyond the annotations without contradicting them.

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

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

The description is well-structured: it starts with the core purpose, then explains arguments and response format. At around 200 words, it is fairly concise, though some repetition of schema details could be trimmed. Overall, it earns its 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?

Given no output schema, the description thoroughly explains all three return fields (tracked, expired, snapshot_dates) with enough detail for an agent to understand the data structure. It also covers limitations (60-day TTL, decay from daily closes). This makes the tool self-contained.

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

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

Schema coverage is 100% with clear descriptions for both parameters (days and window). The description adds context like the default and max for days and the meaning of window as a snapshot family, but the schema already does a good job, so the added value is marginal.

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 explicitly answers the question 'how long has this edge existed and is it shrinking?'. It distinguishes itself from siblings like polymarket_edges by focusing on historical time-series analysis rather than current snapshots.

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 strong contextual guidance ('a fresh wide edge and a 3-week-old wide edge are different trades'), implying when to use this tool for assessing edge quality. However, it does not explicitly mention when not to use it or list alternatives, so it falls short of a perfect 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 confirm read-only, idempotent, non-destructive behavior. The description adds detailed behavioral context: it walks the order book ladder, returns specific fields (e.g., top_of_book, vwap_fill_price, slippage_pp), and warns about forced directional risk. 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?

Despite length, the description is well-structured with headings (SINGLE-MARKET, BASKET, USE THIS) and front-loaded core purpose. Every sentence adds value, no fluff. Format uses clear lists and returns information efficiently.

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

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

No output schema exists, so the description must fully explain return values. It does: listing all return fields for both modes (e.g., top_of_book, capture_ratio, thin_legs). Combined with annotations, it provides complete context for an agent to understand tool behavior and return format.

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 goes beyond by explaining parameter behavior in both modes (e.g., size_usd interpretation for buys vs sells, clamp range 10–1,000,000, side defaults auto for basket). It adds significant meaning beyond the schema descriptions.

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

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

The description clearly states it is a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly calls out usage before specific sibling tools (polymarket_arbitrage, polymarket_edges), making its purpose distinct.

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

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

The description provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why (theoretical overround not capturable, partial fills cause directional risk), offering clear when-to-use and when-not-to-use context.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds substantial behavioral context: it explains the two modes, the response structure (per-venue prices, top spreads), safety fields (compatibility_warning, temporal_alignment), and counters for skipped comparisons. 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 informative but lengthy and dense, with numerous clauses and all-caps labels. It could be more concise while retaining key points. The structure (purpose, modes, response, safety fields) is logical but the verbosity reduces readability.

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

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

Despite the lack of an output schema, the description comprehensively explains the response (prices, spreads, top_spreads_pp) and safety fields (compatibility_warning, temporal_alignment, skipped counters). For a complex tool with multiple modes and edge cases, this is exceptionally complete.

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

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

The schema has 100% description coverage with basic parameter descriptions. The tool description adds value by listing the 10 topic shortcuts, explaining the override behavior for explicit tickers, and providing examples. This goes beyond what the schema alone offers.

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 computes cross-venue spreads between Kalshi and Polymarket for same resolving question, and explains two modes (topic shortcuts and explicit tickers). However, it does not explicitly distinguish from sibling tools like polymarket_arbitrage, which could cause confusion about when to use which.

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 detailed when-to-use guidance: it explains the two modes, warns that most pre-mapped topics return compatibility warnings (so pre-mapped ≠ tradeable), and describes conditions where spreads are meaningless due to temporal misalignment or non-equivalent bet shapes. This is exemplary usage guidance.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false. The description complements by stating the return includes attribute rows and geometry, adding value 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?

Three sentences with no fluff: first states main action, second lists parameters concisely, third provides a useful usage tip. Front-loaded and efficient.

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

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

For a 6-parameter tool with full schema coverage, the description covers purpose, parameters, and return type (attributes and geometry). No output schema, but the description suffices. Could mention output format explicitly.

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

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

Schema coverage is 100% with descriptions. The description adds context like SQL-like syntax, comma-separated fields, and default values, plus concrete examples that enhance understanding.

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

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

The description clearly states the tool queries an ArcGIS Feature/Map Service layer by URL, with SQL-like parameters. It distinguishes from siblings like search_datasets by indicating the URL comes from that tool.

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

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

The description implies the URL should come from search_datasets and provides an example of sampling data. It could explicitly state when not to use it or list alternatives, but guidance is clear enough.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds scope (scoped to identifier) and pairing with remember/forget, going 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?

Three sentences, front-loaded with primary action, then purpose, then scope and pairing. 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?

With 1 optional parameter, no output schema, and comprehensive annotations, the description sufficiently covers usage, scope, and pairing context. 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% for the single optional parameter. Description clarifies the key param's purpose and behavior ('omit to list all keys'), adding meaning beyond the schema's type and description.

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

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

Description states 'Retrieve a value previously saved via remember, or list all saved keys', specifying a clear verb (retrieve/list) and resource (saved memory). Distinguishes from siblings 'remember' and 'forget' by name, avoiding confusion.

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 context: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' Implicitly shows when to use, but does not explicitly state when not to use or name 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?

The description states that setting mark_read:true flags events as read and alters future results, implying a side effect. This contradicts the readOnlyHint annotation which declares no side effects. The description fails to disclose or reconcile this behavioral trait.

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

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

The description is concise with four focused sentences. It front-loads the purpose, then lists key properties, filter options, and behavioral notes. Every sentence adds value with no redundancy.

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

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

For a read-only tool with 5 parameters and no output schema, the description adequately covers return fields (source, citation_uri, raw event payload), filtering, mark_read behavior, and alternative access. It lacks explicit mention of limit and unread_only, but schema covers them. Overall, sufficient for agent use.

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 useful context for type and since parameters with examples (e.g., 'sec_8k') and clarifies mark_read behavior. However, limit and unread_only are not mentioned in the description, but they are adequately described in the schema.

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

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

The description clearly states the tool 'pulls fired events from your subscription feed' and specifies the data returned (source, citation_uri, raw event payload). It distinguishes from sibling tools by focusing solely on alerts, with no overlap in purpose.

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

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

The description mentions polling works fine and provides an alternative endpoint for scripts and dashboards, implying when to use the tool programmatically. However, it does not explicitly compare to other MCP tools or provide when-not-to-use guidance.

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

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

The description adds significant context beyond annotations: it reveals the tool fans out to multiple sources, explains the news fallback (GDELT preferred, GNews when rate-limited), mentions soft-fail for USPTO, and describes the return format (grouped changes, total count, citation URIs).

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 example queries and is dense with information. However, it could be slightly more structured (e.g., bullet points for sources) but remains concise for the complexity.

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

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

Given the complexity (multiple sources, fallback logic, multiple date formats, no output schema but description mentions return structure), the description is remarkably complete. It also properly references the sibling tool for static profiles.

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 value by explaining 'since' accepts ISO or relative shorthand (e.g., '30d' for typical monitoring) and that 'value' can be ticker or CIK. This is helpful beyond the schema descriptions.

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

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

The description uses specific verbs ('change feed') and resources ('SEC EDGAR', 'GDELT→GNews', 'USPTO') and clearly distinguishes from the sibling 'entity_profile' tool. Example queries like 'What's new with X' make the purpose immediately clear.

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

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

Explicitly states when to use this tool (e.g., 'latest on Y', 'updates on Acme') and when to use the alternative ('Use entity_profile instead when you want the static profile'). Also describes fallback behavior for news API.

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

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

Annotations provide idempotentHint=true and destructiveHint=false. Description adds valuable context: scoping by identifier, persistent memory for authenticated users, 24-hour retention for anonymous sessions. 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?

Concise, front-loaded with main purpose, and structured logically. 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 simplicity of the tool (2 params, no output schema), the description covers all necessary aspects: purpose, usage context, scoping, persistence, and related tools. No gaps.

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

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

Schema coverage is 100% with descriptions for key and value. Description adds practical examples of key formats (subject_property, target_ticker), which enriches understanding beyond the schema alone.

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

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

Description clearly states the tool's purpose with specific verb 'Save data' and resource 'data the agent will need to reuse later'. It distinguishes from siblings by referencing recall and forget, and provides concrete examples of usage (resolved ticker, target address, etc.).

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

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

Explicitly states when to use ('when you discover something worth carrying forward') and mentions complementary tools (recall, forget). Provides context on persistence for authenticated vs. anonymous sessions.

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

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

The annotations already establish safety (readOnly, idempotent, non-destructive). The description adds valuable behavioral context: internal cascading through multiple lookup endpoints, graceful degradation when GLEIF/OpenFIGI is unavailable, and explicit handling of unresolved identifiers under an `unresolved` field. These details go beyond what annotations provide, enhancing the agent's understanding of side effects and limitations.

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

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

The description is a single dense paragraph but well organized: it opens with relatable queries, states the core purpose, then details the supported types and behavior. Every sentence contributes information, though the ending sentence about replacing manual lookups is slightly redundant with the cascading mention. Overall, it is appropriately sized for the tool's complexity.

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

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

Despite having no output schema, the description covers the required return concepts: source-labeled identifiers, unresolved handling, and graceful degradation. It explains what company and drug lookups return and even cites a specific URI scheme. Some gaps remain, such as how multiple matches are disambiguated, but the description is largely complete for operational use.

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

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

The input schema already provides thorough descriptions for both parameters, including examples. The description adds further meaning by explaining what each entity type returns (e.g., company resolves CIK/ticker/LEI/FIGI, drug returns RxCUI/ingredient/brand), and provides input format examples. While the schema covers the basic semantics, the description enriches the purpose of the 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's purpose: resolving user-spoken names to canonical identifiers required by other tools. It provides concrete example queries and explicitly distinguishes itself from siblings by advising to use it FIRST when you have a name but need an ID. The verb 'resolve' is specific and the resource is unambiguous.

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

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

The description explicitly instructs to 'Use FIRST whenever you have a name but need an ID,' providing a clear trigger condition. It also enumerates supported entity types and explains what each returns, giving the agent enough context to decide between this and other tools. While it doesn't name alternatives explicitly, the 'FIRST' priority marker effectively differentiates it.

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

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

Discloses that it probes each entity with ai_visibility_check, ranks results, and details free vs. API-dependent model options. Annotations already indicate read-only and idempotent nature; description adds meaningful behavioral depth.

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: first states the core action, second provides use case and return structure. No redundant or irrelevant information.

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

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

Despite lacking an output schema, the description fully covers the tool's behavior, parameter roles, return format (ranked list with metrics), and typical use case, leaving no major gaps.

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

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

All parameters have schema descriptions, but the description adds value by explaining the 'entities' array's first element as subject, the role of 'context' for disambiguation, and the default model in 'models'.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check, ranking by score, and surfacing most/least recognized. It distinguishes itself from single-entity tools like ai_visibility_check and generic compare_entities.

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

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

Provides a concrete use case: competitive AI-marketing audits with an illustrative question. Though it doesn't explicitly exclude alternatives, the context is clear enough for an agent to decide when 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?

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses critical behavioral details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30 seconds, and sources_failed lists timeouts. This fully informs the agent of potential delays and error handling.

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

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

The description is information-dense and well-structured, front-loading purpose and usage, then detailing output, limitations, and fallback behavior. At about 6 sentences, it is slightly long but justified by the complexity; 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 fully explains the return structure (summary block fields, per-advisory detail, links, alternative versions) and covers edge cases like partial failures and ecosystem scope. It provides a complete picture for the agent to use the tool effectively.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds that package is an npm package name (including scoped) and version defaults to latest, which aligns with the schema but doesn't provide significant additional semantic meaning beyond the schema's own descriptions.

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

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

The description clearly states it's a composite check for deciding whether to add an npm package, specifying data sources (deps.dev and bundlephobia) and the return structure. It distinctly positions the tool among siblings like 'deep_research' and 'validate_claim' by focusing on npm ecosystem safety and size analysis.

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

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

Explicitly tells when to use: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also specifies limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', providing clear exclusion criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds context about the data source and return fields without contradicting annotations.

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

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

Two sentences, no redundancy, front-loaded with the main purpose. 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?

The description explains what the tool searches, what it returns, and how to use the output. With good annotations and no output schema, this is sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description does not add new parameter details beyond mentioning keyword and URL, but it provides downstream usage context.

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

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

The description clearly states the tool searches City of Sarasota GIS open geospatial datasets by keyword, specifying the resource and action. It differentiates from siblings like query_layer and layer_info by indicating the output is a list of dataset metadata.

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

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

The description explicitly tells when to use (searching for datasets) and what to do with the output ('pass that url to query_layer / layer_info'), providing clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral details: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char overlapping windows, and has a 200K char cap with truncation and flagging.

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 highly concise yet complete. It front-loads the core purpose, then adds usage guidelines, and finally technical details. Every sentence is necessary and adds value.

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

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

Given no output schema, the description fully explains what is returned: top-N passages with character offsets and similarity scores. It also covers capabilities, limits, and integration with sibling tools, making it complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by specifying the char limit for 'text', providing natural examples for 'query', and giving explicit range and default for 'limit'. This extra clarity justifies a score of 4.

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

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

The description clearly states the verb 'search' and the resource 'inside a fetched record'. It provides concrete examples (SEC 10-K, article, tool result) and distinguishes itself from sibling tools like ask_pipeworx_grounded by explaining their relationship.

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

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

The description explicitly states when to use this tool: 'when the record is too big to cram into the prompt'. It also explains the pairing with ask_pipeworx_grounded, giving a clear alternative and workflow 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 (readOnlyHint=false, idempotentHint=true) are consistent. The description adds behavioral details: creation side effect, delivery channel constraints (phone verification, 10/day SMS cap, webhook auto-disable after 10 failures), and one-time webhook secret. 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 a single, information-dense paragraph. It front-loads the main purpose and then systematically covers types and delivery. While comprehensive, it is not overly verbose for the complexity involved.

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

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

The description covers the main aspects: purpose, requirements, supported types, parameter details, delivery options, and constraints. Although there is no output schema, the return value is mentioned. For a tool with nested objects and multiple types, it is 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%, but the description adds significant value beyond the schema: detailed explanations for 'type' enum values, comprehensive examples for 'params' per type, and thorough description of 'delivery' channels including constraints and the webhook HMAC signing. This greatly aids correct invocation.

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

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

The description clearly states the action ('Create a proactive monitoring subscription') and resource ('live-data event stream'), with explicit return value ('Returns the new subscription id'). It distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe'.

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

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

The description provides clear context: when to use (to create a subscription), requirements (Pipeworx OAuth account), and supported types with examples. It does not explicitly state when not to use or alternatives, but the context is sufficient.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds that it returns category-bucketed example questions from the live catalog, with tool and argument shapes. No contradictions.

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

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

Description is comprehensive but somewhat lengthy. However, it is well-structured with aliases at the start and clear enumeration of categories. Slight reduction possible without losing clarity.

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

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

Despite no output schema, the description fully explains the return format (category-bucketed example questions with tool/argument shapes). Given the simple one-parameter input, this is complete.

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

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

Schema coverage is 100% for the single topic parameter. Description elaborates with exact allowed values and explains behavior when omitted, adding value beyond the schema.

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

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

The description clearly states the tool is an onboarding entry point that returns category-bucketed example questions with tool and argument shapes. It distinguishes itself from siblings by being the first tool to use when unfamiliar with Pipeworx.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also provides guidance on passing a topic to focus and omitting for full spread.

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

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

Adds behavioral context beyond annotations: deactivates (not deletes), historical events remain via recent_alerts, ownership enforced. Consistent with idempotentHint and destructiveHint.

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

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

Two sentences, front-loaded with action, clear and minimal. 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?

Complete for a simple tool: covers purpose, behavior, side effects (deactivation, historical data), and ownership. No missing aspects.

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

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

Schema covers id parameter fully (100% coverage). Description adds no additional meaning to the parameter beyond what schema already provides.

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

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

States clearly it cancels a subscription by id. Distinguishes from deletion (deactivates vs deletes) and ownership enforcement. Sibling tools like subscribe and list_subscriptions further differentiate.

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?

Specifies when to use (cancel a subscription) and ownership constraint. Does not explicitly mention alternatives or when not to use, but siblings provide implied context.

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

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

The description goes well beyond the annotations by explaining the internal fallback behavior (financial fast path vs. grounded pipeline), the meaning of each verdict, and the critical caveat that could_not_verify means the check did not happen and carries verification_error{stage,detail}. It also clarifies unsupported means no source was found. This adds substantial behavioral context that annotations do not provide.

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

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

The description is well-structured: it starts with natural-language triggers, states the purpose, explains the two execution paths, lists return fields, and highlights important caller caveats in a clear "IMPORTANT" block. While it is longer than a typical tool description, every sentence earns its place and the information is front-loaded with the core purpose.

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

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

Given the absence of an output schema, the description sufficiently explains the return verdicts (confirmed, refuted, etc.), the actual value with citation, and reasoning. It also addresses edge cases like could_not_verify and unsupported, which are crucial for correct usage. The two-path execution model is fully described, making the tool's behavior predictable and complete.

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

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

Schema coverage is 100%, and the schema already describes both parameters with examples (e.g., claim and tolerance_pct). The description adds some context by mentioning tolerance is capped at 5 and can be overridden for hallucination detection, but this is also present in the schema's description. Since the schema does the heavy lifting, the description adds marginal value, matching the baseline of 3.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It lists common phrasings ("Is it true that…"), specifies the verb "validate" and resource "factual claims," and distinguishes from siblings by describing the structured SEC EDGAR path for financial claims and grounded pipeline for all others. This makes it distinct from broader tools like ask_pipeworx or deep_research.

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

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

The description explicitly says "Use whenever the agent needs to check whether something a user said is factually correct," providing clear when-to-use guidance. It also differentiates between company-financial claims and other factual claims, explaining the routing. However, it does not name alternative tools or explicitly state when not to use it, so it falls short of full exclusionary guidance.

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