Arcgis Vilas

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds specific behavioral details: uses Workers AI Llama-3.3-70b by default, requires BYO key for Anthropic, and returns per-model scores with confidence, signals, and raw_response. No contradictions.

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

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

The description is concise (three sentences) and efficiently structured, with the main action stated first and no 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?

Despite no output schema, the description details the return format (per-model and combined view). All parameters are explained, and the tool's complexity is well-covered for an agent to use correctly.

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

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

Schema coverage is 100%, and the description adds value by explaining the default model, the role of _apiKey, and how context disambiguates entities. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's function: probing LLMs for knowledge about an entity and scoring visibility. It specifies the default model and optional Anthropic probe, and distinguishes from siblings by focusing on AI visibility measurement for marketing audits.

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 context for when to use the tool, such as AI-marketing audits and pre-launch brand checks. It explains the optional _apiKey requirement for Anthropic but does not explicitly compare with sibling tools like 'scan_competitor_ai_presence'.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, so the safety profile is encapsulated. The description adds meaningful behavioral context: it explains the routing mechanism, citation URI output, tier availability, and performance ('one fast call'). No contradiction exists, and the added context goes beyond simply restating 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 longer than average but front-loaded with the core value proposition, then usage triggers, examples, and alternatives. Some redundancy exists ('PREFER OVER WEB SEARCH' repeated in the later trigger list), but overall the organization is clear and every major point earns its place for a default entry-point 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?

The description covers the tool's purpose, supported domains, trigger phrases, examples, alternatives, tier availability, and return format. It covers most relevant context for a complex router tool. Minor gaps include lack of guidance for unsupported questions and no mention of output structure beyond citation URIs, but overall it is sufficiently complete.

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

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

Schema description coverage is 100%, with all six parameters documented (question plus five aliases). The description does not add detail beyond the schema’s parameter semantics; the examples are about usage scenarios, not parameter syntax or formats. Per the rubric, the high coverage gives a 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 routes questions to 5,529 tools across 1,455 sources, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research and positions ask_pipeworx as the default starting point, providing a specific verb+resource+scope.

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-to-use guidance (factual questions about real-world data, prefixed phrases like 'what is', 'look up') and equally explicit alternatives: use ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part fan-out, and notes that breaking-news is already handled. This level of differentiation with named sibling tools far exceeds the minimum.

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, and idempotentHint. The description adds valuable behavioral context about live candidate routing improvements, the current inactive state, and that results are compared to the stable router. It could have detailed potential variability in responses, but the existing context is strong enough to earn a 4.

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 moderately sized but each sentence provides distinct, non-redundant information: beta status, equivalence to ask_pipeworx, current inactive state, usage guidance, and non-fallback warning. It is front-loaded with the key concept and not unnecessarily verbose.

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 clarifies the response shape is identical to ask_pipeworx, which an agent can reference. It also mentions the full router nature and the 5,529 tools, giving enough context to invoke appropriately. Minor gap: it doesn't describe what the response actually looks like, but the pointer to ask_pipeworx suffices.

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

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

Schema description coverage is 100% with all parameters described as aliases for 'question'. The main description for 'question' explains aliases, and the schema itself is self-sufficient. The tool description adds no extra parameter meaning, so the 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 this is a beta version of ask_pipeworx, a universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the sibling ask_pipeworx by emphasizing the experimental live routing improvements, making the purpose specific and differentiating.

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 directs to 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies that it is not a fallback but a full working router. This gives clear when-to-use guidance and contrasts with the stable router for deciding merges.

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

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

The description discloses exact behavior beyond annotations: on success returns {answer, evidence, confidence, source, fetched_at, refusal_reason:null}, and on failure returns explicit refusal with enumerated refusal_reason values. It also mentions the additional LLM call cost and the fact it picks from 5,529 tools across 1,455 sources. Annotations (readOnlyHint, openWorldHint, idempotentHint) are not contradicted; the description enriches the agent's understanding of internal routing and failure modes.

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

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

The description is front-loaded with the core purpose and then provides structured detail about return values, refusal reasons, and usage guidance. It is longer than two sentences but every sentence adds relevant information (return format, cost, alternatives). Slightly dense but not wasteful; each sentence earns its place.

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

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

Given there is no output schema, the description fully covers return values, refusal scenarios, and the intended use context. It also explains the extra cost and comparable sibling tool (ask_pipeworx). No critical gaps remain for an agent to decide when and how to invoke the tool correctly.

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

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

Schema coverage is 100% with all six parameters documented as aliases for 'question' (query, q, prompt, text, input). The description does not add parameter-level semantics beyond what the schema already says; it focuses on tool behavior, not the question parameter. Baseline 3 applies because the schema does the heavy lifting and the description adds no unique parameter guidance.

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 defines a specific operation: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly states the tool's function and scope (high-stakes reads) and differentiates from sibling ask_pipeworx by noting 'Same routing as ask_pipeworx' but with an extraction step using only tool results. This is a specific verb+resource+mode.

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 usage conditions: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and lists example domains. It also gives exclusion guidance: 'prefer ask_pipeworx for casual lookups,' naming the alternative and explaining the cost tradeoff (one extra LLM call). This is clear when-to-use and when-not-to-use guidance.

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

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

Goes far beyond annotations by detailing safety mechanisms (low-confidence short-circuit, closed market handling, wide spread notes), resolver contract, parent event extraction, and resolution-rule risk. All critical for correct agent 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?

Very detailed and front-loaded, but lengthy. Every sentence adds value, but the paragraph could be streamlined to improve quick parsing by an agent without losing critical details.

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

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

Despite no output schema, the description comprehensively covers output fields (market, analysis, evidence), resolver contract, parent event extractor, news fields, safety behaviors, and resolution-rule risk. All necessary context 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%, baseline 3. Description adds meaningful context: market parameter explains slug/URL/text inputs, depth explains 'quick' vs 'thorough', include_raw explains summarized vs full payloads. Adds value beyond schema.

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

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

The description clearly states the tool's purpose: researching Polymarket bets by pulling Pipeworx data. It specifies input formats (slug, URL, text) and output (evidence packet + comparison), and distinguishes from sibling tools by focusing on comprehensive 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?

Provides explicit usage examples ('should I bet on X', 'what does the data say about Y') and classifier options. However, lacks explicit guidance on when NOT to use or how it compares to siblings like polymarket_edges or deep_research beyond the general research focus.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: off-calendar fiscal year handling, results sorted by primary metric, and citation URIs. It does not mention rate limits or data freshness, but adds significant behavioral details beyond annotations.

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

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

The description is front-loaded with example queries and uses bold for key guidance. It is relatively long but every sentence adds value. A minor improvement would be to trim redundancy, but it's well-structured.

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

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

With no output schema, the description covers return data (paired data + citation URIs) and handles both entity types completely. For a tool with only 2 parameters and clear behavior, it is fully 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%, so baseline is 3. The description adds meaning by explaining the type enum (company vs drug) and the format for values (tickers/CIKs vs drug names), plus the 2-5 range. This is helpful 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 compares 2-5 companies or drugs, provides example queries, and explains what data is pulled for each type. It distinguishes itself from sequential lookups and sibling tools like entity_profile.

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

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

Explicitly instructs to prefer this tool over sequential single-pack lookups when comparing entities, and gives concrete example queries such as 'which is bigger' or 'rank these companies'. This provides clear when-to-use guidance.

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

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

Annotations only declare read-only, open-world, idempotent, non-destructive hints. The description adds substantial behavioral context beyond that: account/payment requirements, parallel routing to 5,529 tools, the gaps[]/contradictions[] mechanism, semantic excerpting, citation fetchability, and expected latency. There is no contradiction between description and 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 and contains some redundancy (e.g., 'this is NOT open-web search' repeated, and depth details appear both here and in the schema). However, the length is largely justified given the tool's complexity (account requirements, many sources, parallel routing, gap handling, output format, latency). The structure is logical, front-loading the most critical info (account requirement, core purpose, alternatives) before diving into mechanics.

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?

There is no output schema, so the description must explain the return value, and it does thoroughly: findings packet with verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], and hop fields. It also covers account/auth requirements, timing expectations, and when to avoid this tool. For a tool of this complexity, the description is remarkably complete for an agent to decide when to use it and what to expect.

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 each parameter is described, including the depth enum's meanings. The description adds value beyond the schema by explaining the practical implications of depth choices ('re-angles unanswered gaps', 'chases leads', paid plan requirement), and clarifies that the question can be broad/multi-part. Not a full 5 because the schema already carries significant semantic weight for the depth 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 states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources ... in ONE call'. It clearly distinguishes itself from siblings by contrasting with ask_pipeworx and noting 'this is NOT open-web search'. The purpose is concrete and actionable.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' with examples. Also gives clear exclusions and alternatives: 'For a single lookup use ask_pipeworx' and for breaking news 'prefer ask_pipeworx'. It even handles the signed-in/not-signed-in case by directing users to ask_pipeworx. 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 already indicate readOnlyHint=true and idempotentHint=true. The description adds value by explaining that returned results include full input schemas with curated examples and are 'ready to call directly.' This complements the annotations without contradiction.

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

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

The description is a single paragraph that efficiently conveys key points. However, it lists many domains, which is helpful but slightly verbose. It could be more concise while still being informative.

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

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

Given the tool's complexity (6 parameters, mostly aliases) and lack of output schema, the description sufficiently explains what the tool returns and how to use it. It covers the agent's needs for initial discovery.

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 parameters are well-documented. However, the description adds meaning by listing example queries ('analyze housing market trends', 'look up FDA drug approvals') and mentioning aliases (task, q, description, search). This helps the agent understand how to use the query parameter 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's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, etc.) and details what it returns (top-N relevant tools with names, descriptions, and schemas). This makes it distinct from sibling tools.

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

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

The description explicitly advises: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context for when to use it, though it does not explicitly exclude alternative uses.

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 readOnly, openWorld, idempotent. Description adds significant behavioral detail: fans across multiple sources, returns specific fields, soft-fail for patents, GDELT→GNews fallback, sort order for fundamentals. 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 detailed but well-structured: starts with usage examples, then behavior, return content list, limitations. Some redundancy (e.g., names not supported appears twice) but overall efficient 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?

Despite no output schema, description fully enumerates return fields (cik, company_name, recent_filings with URIs, fundamentals with specific items, patents, news, LEI) and specifies limits and sort order. Covers all major aspects for a holistic profile tool.

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

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

Schema coverage is 100%, description adds extra context: examples ('AAPL', '0000320193'), constraint that names not supported, and parameter roles for ticker vs CIK. Adds value beyond schema but schema already covers basics.

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 provides a 'full cross-source profile of a US public company' in one call. Includes representative queries and explicitly distinguishes from chaining single-source lookups.

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

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

Explicitly says to prefer over chaining when user asks for holistic view, and documents that names are not supported (referring to resolve_entity). Provides clear when-to-use and when-not-to-use.

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

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

Description adds context beyond annotations: it explains the purpose of deletion (clear stale/sensitive data). Annotations already indicate destructive and idempotent; 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 concise sentences; first focuses on purpose, second on usage. No unnecessary words.

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

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

For a simple one-parameter tool with no output schema, the description fully covers what, when, and with which sibling tools to 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%, and the description does not add further details about the 'key' parameter beyond the schema description.

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

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

The description clearly states the verb 'Delete' and the resource 'memory by key'. It is specific and distinguishes from sibling tools 'remember' and 'recall'.

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

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

Explicitly provides use cases: stale context, task completion, clearing sensitive data. Pairs with remember and recall, but does not explicitly state when not to use or give alternatives.

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

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

The description explains the process: fetches the page, extracts title/description/links, emits markdown format. This adds behavioral context beyond the annotations (readOnlyHint, idempotentHint) which already indicate safe operation. No contradictions.

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

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

Three focused sentences with no wasted words. The first sentence states purpose and outcome, the second explains the method, the third lists use cases. 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?

With two parameters and no output schema, the description adequately explains input (URL, optional max_links) and output (single text blob in llms.txt format). Could mention error handling or validation, but overall covers what's needed.

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

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

Schema coverage is 100%, and the description mirrors the schema's parameter descriptions without adding new meaning (e.g., 'Full URL of the site to summarize' is identical to schema). No additional semantics beyond what the schema provides.

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

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

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

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

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

The description provides three concrete use cases (getting a client's site indexed, drafting for own project, auditing competitors) but does not explicitly state when not to use it or suggest alternatives. Still, the context is clear and actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds value by specifying exactly what is returned (fields, geometry, count, capabilities), providing behavioral context beyond the annotations.

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

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

Single, front-loaded sentence with no wasted words. Efficiently communicates the tool's purpose and outputs.

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 this simple tool: one parameter, no output schema, and the description covers all essential aspects of behavior and return values.

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

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

Schema coverage is 100% with a clear description and example. The tool description repeats the requirement for a URL but does not add new meaning beyond the schema. Baseline score of 3 applies.

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

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

Clearly states the verb (Get), resource (ArcGIS layer schema), and the specific outputs (fields, geometry type, count, capabilities). Distinguishes from siblings like query_layer which actually queries data.

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

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

Implies usage by requiring a URL, but does not explicitly state when to use this tool versus alternatives like query_layer or search_datasets. No when-not or exclusionary guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, confirming safe read operation. Description adds value beyond annotations by specifying return fields and the include_inactive parameter semantics.

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 (30 words) with no wasted words. Purpose is front-loaded. 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?

Tool is simple (list, one optional param, no output schema). Description covers purpose, parameter behavior, return fields, and usage guidance. Annotations cover safety. Complete for its complexity.

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

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

Schema coverage is 100% with a good parameter description. Description adds meaning by listing return fields (id, type, etc.) not in schema, and implies that the default is active subscriptions only.

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 'List the caller's active subscriptions' with specific verb and resource. It also lists return fields (id, type, params, created_at, last_fired_at, fire_count). Distinguishes from siblings like subscribe/unsubscribe.

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

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

Description explicitly advises when to use: 'review what you're monitoring before adding more or to find an id to cancel.' It does not explicitly list alternatives but contextually implies when not to use (e.g., for other subscription operations).

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

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

Beyond the annotations (readOnlyHint=false, etc.), the description discloses meaningful behavioral details: filing without an account returns a claim_token, the token can be used later to read resolution status, feedback is rate-limited to 5 per identifier per day, and it does not count against tool-call quota. These go well beyond structured annotations and help the agent set expectations.

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

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

The description is dense but every sentence contributes: purpose, use cases, exclusions, content guidance, claim_token behavior, escalation cadence, and rate limits. It is front-loaded with the primary purpose and maintains a logical flow without redundancy.

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

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

Given the tool's complexity (4 parameters, nested context object, no output schema, all params optional), the description provides a complete picture: what to include in feedback, how to scope it to Pipeworx tools, how to use claim_token for follow-up, and operational constraints like rate limits. No critical information is missing.

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

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

Although schema coverage is 100%, the description adds significant semantic value: it clarifies how to use claim_token (return it later with no other arguments), instructs not to paste end-user prompts, and gives guidance on message specificity. This enriches the bare parameter descriptions with practical usage details.

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

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

The description opens with a clear, active purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It names the resource (Pipeworx team/connection) and distinguishes this from sibling tools by explicitly limiting it to Pipeworx-served tools only, not other MCP servers.

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-to-use guidance: bugs, feature/data_gap requests, and praise, each with concrete examples. It also provides a clear exclusion ('if the tool came from a different MCP server... file it with that server instead') and explains the claim_token workflow for following up, which is strong usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds details: aggregated signal from analytics engine, no PII, caching behavior (5min-1h), and output composition (pack, tool, count). No contradictions.

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

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

Concise, well-structured with bullet points for use cases, no redundant sentences. Every sentence adds value.

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

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

Given only one optional parameter and no output schema, the description adequately covers return values, data source, privacy, and caching. Minor omission: no example response or pagination info, but not critical for this tool.

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

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

The single parameter 'window' is fully described in the schema via enum. The description adds context about choosing shorter vs longer windows for different insights, going 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 returns 'top tools, top packs, and total call volume' over configurable time windows. It distinguishes itself from siblings like 'ask_pipeworx' or 'discover_tools' by focusing on aggregated trending data, not queries or general discovery.

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

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

Three specific use cases are listed (discovering hot data sources, confirming canonical tools, checking alignment). Window choices are explained. However, no explicit guidance on when not to use or alternatives among siblings.

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

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

The description goes well beyond annotations by detailing scanning behavior, partition checks, fill checks, and trade recommendations. It warns about not trading when realizable edge is non-positive, adding valuable behavioral context.

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

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

The description is well-structured with clear sections and front-loaded purpose. While it is verbose, every sentence contributes meaningful information, so it remains 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 tool's complexity and lack of output schema, the description thoroughly explains input modes, internal logic, and response structure including fields like gap_pp, suggested_trade, and partition_check. It is complete and 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%, but the description adds meaning by explaining what event slugs and topic seeds do, and how the tool processes them. This adds value beyond the basic schema descriptions.

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

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

The description states a specific verb ('Find') and resource ('arbitrage opportunities on Polymarket') and explains two modes. However, it does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_edge_tracker, which reduces the score from a 5.

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

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

The description explicitly tells when to use each parameter: no args for trending scan, 'event' for single-event mode, 'topic' for cross-event scan, and recommends event for specific markets. It also references an alternative tool (polymarket_fill_risk) for custom sizing, providing clear 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 goes far beyond annotations by detailing the three segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), the specific models and filters used, the output structure (by_segment, fed_candidates, diagnostics), and caching behavior. Annotations only indicate read-only, idempotent, non-destructive; the description adds rich behavioral context without contradiction.

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

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

The description is comprehensive but verbose, exceeding 500 words. It is well-structured with sections and bullet points, but the level of detail (e.g., specific model parameters like tennis α=1.02) may be excessive for quick understanding. Front-loaded with purpose, but could be trimmed for conciseness.

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

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

Despite having 9 parameters and no output schema, the description covers all necessary context: use case, segments, filters, output structure (by_segment, diagnostics), caching, and tradeable-edge knobs. It leaves no significant gaps for an agent to understand the tool's behavior and outputs.

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 decent parameter descriptions. The tool description mentions tradeable-edge knobs but does not add significant new meaning beyond what the schema already provides. It provides some context for min_partition_leg_kelly and min_kelly, but overall the description does not substantially enhance parameter understanding.

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

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

The description clearly identifies the tool as scanning Polymarket markets for opportunities where Pipeworx data disagrees with market price. It explicitly states it is built for 'what should I bet on today' and distinguishes from siblings like polymarket_arbitrage by focusing on Pipeworx data disagreements.

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

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

The description provides clear context for use: discovering betting opportunities from data disagreements. It mentions tradeable-edge knobs and caching, making usage straightforward. However, it lacks explicit when-not-to-use guidance or direct comparisons to sibling tools, like stating when to use polymarket_arbitrage instead.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as true/true/true/false. The description adds extensive behavioral detail: it reads snapshots, returns time-series of edge_pp_net, first_seen, trend, decay_pp_per_day, expired opportunities with lifespan_days, and snapshot dates. It also explains limits (60-day TTL, snapshot start, daily closes vs intraday). This fully discloses behavior without contradicting annotations.

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

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

The description is front-loaded with the key question it answers, then provides structured details on response arrays and limits. It is somewhat dense but well-organized. Each sentence adds value, though it could be slightly more concise without losing information.

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

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

Given the complexity (time-series, decay computation, edge cases like expired opportunities, snapshot gaps, TTL limits), the description covers all relevant aspects. It explains the return format fully (though no output schema), including edge cases and constraints. The agent has enough information to understand inputs, outputs, and limitations.

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

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

Schema coverage is 100% with descriptions for both parameters (days, window). The description adds context: days default 14, max 30; window defaults '1wk' and lists snapshot families (24hr, 1wk, 1mo). It also explains window as 'snapshot family'. This adds value but does not significantly extend beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool provides edge persistence and decay telemetry, answering 'how long has this edge existed and is it shrinking?'. It details the response structure (tracked, expired, snapshot_dates) which reinforces its purpose. However, it does not explicitly differentiate itself from sibling tools like polymarket_edges or polymarket_arbitrage, leaving some ambiguity for an AI agent.

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 understanding edge age and decay through the question 'how long has this edge existed and is it shrinking?'. It provides context for when the tool is appropriate but does not explicitly state when not to use it or mention alternatives. The detailed response structure and limits guide appropriate use.

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

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

Annotations already declare readOnlyHint true and idempotentHint true. The description adds significant behavioral context beyond annotations, explaining that it walks the order book ladder, returns fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, and verdict, and highlights 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?

The description is long but well-structured with bold headings and a clear separation of modes. However, it includes some redundancy (e.g., 'each share pays $1') and could be more concise without losing essential details.

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

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

Given the tool's complexity (4 parameters, no output schema, no nested objects), the description adequately covers return fields, mode usage, and risk warnings. It mentions forced_directional_risk and thin_legs, which are critical for understanding the tool's 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 each parameter having a description. The tool description adds further value by explaining the difference between single-market and basket modes, how size_usd is interpreted differently (spend vs. shares), and the default behavior for side in basket mode. This clarifies usage beyond the schema.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', specifying a precise verb and resource. It explicitly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use this tool before acting on those signals.

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 when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also warns about the risks of partial basket fills. However, it does not explicitly state when not to use it.

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

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

Beyond annotations (readOnlyHint, etc.), the description details safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype), explains when spreads are meaningless, and describes the effect of non-equivalent bet shapes. 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?

Well-structured with clear sections (purpose, modes, response, safety fields). Front-loaded with the core idea. However, it is somewhat verbose, particularly in the safety fields paragraph which could be tightened without losing information.

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

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

Given the complexity (3 parameters, no output schema), the description fully covers the response structure, safety fields, temporal alignment, and edge cases. The agent can understand how to interpret results without additional documentation.

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 each parameter. The description adds value by explaining the interaction between `topic` and the explicit override parameters, and gives concrete examples. Minor deduction because the schema already does most of the work.

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

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

The description clearly identifies the tool as computing the spread between Kalshi and Polymarket for the same event. It distinguishes itself from sibling tools like `polymarket_arbitrage` by focusing on cross-venue comparison. The verb+resource combination is specific and unambiguous.

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

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

Explicitly describes two usage modes (topic and explicit tickers), provides the complete list of macro shortcuts, and warns that most pre-mapped topics return compatibility warnings. This gives clear guidance on when to use the tool and what to expect.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that it returns 'attribute rows (and geometry)' and explains pagination with limit/offset, providing useful behavioral context beyond annotations.

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

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

The description is two sentences: the first efficiently lists all key parameters and return, the second provides a practical tip. No fluff, front-loaded with 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?

For a 6-parameter query tool with no output schema, the description covers purpose, parameters, return type, and usage tip. It references prerequisite workflow and assumes ArcGIS knowledge, which is appropriate given the domain.

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 examples, default values for where and out_fields, and explains SQL-like syntax for where/order_by, which adds significant 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 queries an ArcGIS Feature/Map Service layer by URL with SQL-like parameters, distinguishing it from siblings like layer_info (metadata) and search_datasets (finding datasets). The verb 'query' and resource 'layer' are specific.

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

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

The description mentions 'from search_datasets', establishing a workflow context. It provides examples and defaults, but does not explicitly compare to alternatives like layer_info or state when not to use it. Still, usage is clearly implied.

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. The description adds scoping info and the listing behavior, which are useful beyond annotations.

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

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

Three sentences, no fluff, front-loaded with the main purpose, and each 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?

For a tool with one optional parameter and no output schema, the description covers both usage modes and scoping, making it very 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 has 100% coverage with description for the key param. The description adds meaning by explaining that omitting the key lists all saved keys.

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

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

The description clearly states the tool retrieves values saved via remember or lists all keys when omitted, and distinguishes it from siblings like remember and forget.

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

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

It explicitly tells when to use ('look up context the agent stored earlier') and pairs with remember and forget, providing a complete context for usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true, but the description adds valuable behavioral context: it describes the returned fields (source, citation_uri, payload), explains the effect of mark_read (flagging events as read), and notes that subsequent calls exclude marked-read events. 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 approximately 100 words, front-loaded with the core purpose in the first sentence. It efficiently covers filtering, marking read, and alternative access. A few minor redundancies (e.g., 'the same feed is also at...' could be shorter) but overall well-structured.

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

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

For a read-only tool with no output schema, the description sufficiently explains the return value structure (source, citation_uri, payload). It covers all key behaviors (filtering, marking read, polling) and notes an alternative channel. Missing details like pagination limits or error handling, but adequate for typical 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% with descriptions for all 5 parameters. The description adds practical context, e.g., 'Filter by type (e.g. "sec_8k")' and 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' It also mentions limit defaults (1-200, default 50) beyond the schema's description.

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

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

The description uses specific verbs ('Pull fired events', 'Returns the most recent alerts') and clearly identifies the resource (subscription feed with events). It distinguishes from sibling tools focused on subscription management (e.g., list_subscriptions, subscribe) by focusing on reading fired alerts.

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

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

The description explains filtering options (type, since, mark_read, unread_only) and mentions polling is fine. It also notes the same feed is available as an HTTP endpoint for scripts/dashboards, providing an alternative. However, it does not explicitly state when not to use this tool versus other sibling tools.

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

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

Annotations already indicate read-only, idempotent behavior. The description adds valuable behavioral detail: fan-out to three sources, GDELT→GNews fallback, USPTO soft-fail, and return structure (grouped changes, count, URIs). 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 a single paragraph but logically organized: examples, core function, sources, input details, output overview, and alternative tool. Every sentence adds value. Slightly verbose for the high density of information, but adequately concise overall.

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

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

Given the tool's complexity (multiple sources, fallback, relative dates, return format) and the absence of an output schema, the description covers the key aspects. It explains what the tool returns and what it does not do (static profile). Minor gaps: no example output structure, but sufficient for agent selection.

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

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

With 100% schema coverage, baseline is 3. The description adds significant context: examples of relative shorthand for 'since' ('7d', '30d'), recommendation of '30d' or '1m', explanation of 'value' accepting ticker or CIK, and noting that 'type' currently only supports 'company'. This improves usability.

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

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

The description clearly states the tool's function: a parallel change feed for a company, aggregating SEC filings, news, and patents. It distinguishes itself from sibling tool entity_profile by specifying when to use each. Examples of user queries make the purpose intuitive.

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 contrasts with entity_profile, guiding when to use this tool for change feed vs. static profile. It also implies efficiency with 'ONE parallel call.' However, it does not address other potential competitors like compare_entities, though the focus on temporal changes narrows usage well.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. Description adds context: scoped by identifier, persistence details (24 hours for anonymous, persistent for authenticated), and key-value storage model. 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 three sentences, well structured, each sentence adds value. Could be slightly more concise, but 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 simple store tool with no output schema, the description covers purpose, usage, persistence, and paired tools. Lacks mention of return value, but the feedback (idempotent) and pairing with recall/forget make it adequate.

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

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

Input schema has 100% coverage with descriptions for both key and value. Description adds naming conventions (e.g., 'subject_property') and type of value, but schema already covers meaning well. A slight bonus for reinforcing usage patterns.

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

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

The description clearly states the tool saves data for reuse, with specific verb 'Save' and resource 'data'. It distinguishes from siblings 'recall' and 'forget' by mentioning them.

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

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

Explicitly provides when-to-use guidance ('when you discover something worth carrying forward') and names alternative tools ('Pair with recall to retrieve later, forget to delete').

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description reveals internal cascading lookups, graceful degradation when external sources are unavailable, and explicit labeling of unresolved identifiers. It also clarifies that identifiers are source-attributed and ownership data is included, adding considerable transparency about behavior.

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

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

The description is dense but well-structured: it opens with example queries, states the core purpose, then details supported types and fallback behavior. While long, every section carries information; the only issue is a wall-of-text format that could benefit from bullet points or clearer separation.

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

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

With no output schema, the description fully covers return values: identifiers, sources, unresolved entries, and enrichment fallback. It also addresses input variants (ticker, CIK, name) and gracefully degrades when external services fail. For a two-parameter tool, this is comprehensive and leaves no significant 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?

The schema provides basic parameter descriptions, with 100% coverage. However, the description adds rich semantic detail: for 'company' it explains the cross-source identity spine (CIK, ticker, LEI, FIGI) and ownership relationships; for 'drug' it specifies RxCUI and ingredient/brand. It also provides input format examples, going far 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's purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides concrete query examples and lists supported entity types (company, drug), distinguishing it from sibling tools like 'compare_entities' or 'entity_profile' by focusing on name-to-ID resolution.

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

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

Explicitly states 'Use FIRST whenever you have a name but need an ID,' giving direct usage guidance. It also notes that 'using resolve_entity replaces 2-3 manual lookups,' which reinforces its utility. However, it does not explicitly mention when not to use it or name alternative tools for exclusion.

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

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

Annotations already indicate readOnlyHint, idempotentHint, openWorldHint, and non-destructive. Description adds that it probes each entity, ranks by score, and returns score, confidence, signal density. No contradictions.

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

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

Two sentences that efficiently convey action, purpose, and output. 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?

All 4 parameters are described, and the output is mentioned (ranked list with score, confidence, signal density). No output schema exists, but the description compensates sufficiently.

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

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

Schema coverage is 100% with descriptions for all parameters. Description adds context that the first entity is the 'subject' and that models and context are optional, but does not significantly enhance 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 compares AI visibility across multiple entities, runs ai_visibility_check on each, ranks by score, and identifies most/least recognized. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

Provides explicit use case: 'competitive AI-marketing audits' with an example. Does not explicitly state when not to use or mention alternatives, but the context is clear enough to guide 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?

Beyond the idempotent/false annotations, the description reveals important behavior: bundlephobia's first measurement can take 5-30 seconds, partial failures degrade gracefully with a 'sources_failed' list, and the tool returns multiple components (summary, advisories, links, alternatives). 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 a single, dense paragraph that efficiently packs purpose, use cases, output details, limitations, and behavioral notes. While it could benefit from bullet points for readability, every sentence serves a purpose and the critical information is front-loaded.

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

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

Despite lacking an output schema, the description enumerates the exact fields returned (is_latest, license, advisory_count, bundle sizes, etc.) and explains partial failure behavior. It covers limitations (NPM only, bundlephobia timeout) and alternate usage for other ecosystems, making it fully self-sufficient.

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

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

The input schema already provides 100% coverage for both parameters (package name with scoped syntax, optional version). The description adds no new semantic information beyond what the schema's descriptions already state, so it meets the baseline expectation without additional 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's purpose as a composite check for adding npm packages, specifying the exact use case ('should I add this npm package to my project'). It names the specific data sources (deps.dev, bundlephobia) and output elements, distinguishing it from simpler tools by emphasizing it's a single call that combines multiple checks.

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 an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. It also provides clear boundaries by noting that other ecosystems (PyPI, Maven, etc.) are not covered in v1 and should be handled via a different tool ('deps.dev:version directly').

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, providing the safety profile. Description adds value by listing return fields and the url for further queries, but does not detail pagination or error behavior.

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

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

Two sentences, front-loaded with the action and scope, followed by return fields and next steps. No redundancy or unnecessary information. Every sentence earns its place.

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

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

Despite no output schema, the description fully explains return fields (name, summary, record_count, owner/org, url) and how to use the url with sibling tools. All 3 parameters are documented in schema. Agent has enough context to invoke and proceed.

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

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

Schema coverage is 100% with clear descriptions for each parameter (limit, query, org_id). Description focuses on output and does not add significant parameter details beyond the schema, earning a baseline 3.

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

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

Description clearly states it searches Vilas County GIS open geospatial datasets by keyword, listing specific categories like parcels, addresses, zoning & public works. It also explains return fields and directs to sibling tools query_layer and layer_info, distinguishing its role.

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: searching datasets by keyword. Provides context by listing return fields and next steps. Does not explicitly mention when not to use or alternatives, but the specific domain makes usage clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Beyond that, the description adds specific details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and character offsets for verification. 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?

A single, well-structured paragraph with each sentence adding distinct value. Front-loaded with purpose, efficient 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?

Despite no output schema, the description explains return values (passages with offsets and similarity scores). It covers behavior, limitations, and pairing with sibling tools, providing complete context for invoking the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds useful examples for the query parameter (e.g., 'supply-chain risk') and clarifies the text parameter's max length, providing extra context beyond the schema's 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 'Semantic search INSIDE a fetched record' with concrete examples (SEC 10-K, article). It distinguishes from siblings by contrasting with fetching whole documents and mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly states 'Use when the record is too big to cram into the prompt' and explains benefits (saves context, returns relevant passages). Also outlines alternative workflow with ask_pipeworx_grounded.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false, consistent with creating a subscription. Description adds behavioral context such as OAuth requirement, delivery limitations (e.g., 10/day SMS cap, webhook auto-disable after failures), which goes beyond annotations.

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

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

Description is dense but well-structured, covering purpose, prerequisites, types, and delivery details in a single paragraph. Minor redundancy (e.g., SMS cap mentioned twice) slightly reduces conciseness.

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

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

For a complex tool with nested objects and no output schema, the description covers return value, parameter details, and behavioral constraints. It is sufficiently complete for effective 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%, baseline 3. Description adds significant meaning by explaining enum values (types), param object structure with examples, and delivery object details (e.g., webhook signing). This adds 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?

Description clearly states the tool creates a proactive monitoring subscription and returns a subscription id. It distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts by specifying its unique function.

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

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

Description explains when to use (proactive monitoring of live data streams), prerequisites (Pipeworx OAuth account), and provides detailed guidance on types and delivery channels. It does not explicitly state when not to use, but the context is clear.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive hints. The description adds value by specifying that calling with no arguments gives a full spread and that the topic parameter focuses results. It also describes the return format, which is not present in annotations.

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

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

The description is somewhat lengthy but well-structured with example queries upfront. Every sentence provides useful information, such as the list of categories and the guidance on tool usage. Minor redundancy could be trimmed, but overall it is 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 tool's simplicity (one optional param, no output schema), the description covers all necessary aspects: purpose, usage context, parameter behavior, and return format. It is sufficiently complete for an agent to correctly select and invoke the tool.

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

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

Schema coverage is 100% with one optional parameter. The description adds meaning beyond the schema by listing example values ('finance', 'pharma', etc.) and explaining the effect of omitting the parameter. This helps the agent understand usage better than the schema alone.

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

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

The description clearly states that the tool returns category-bucketed example questions with associated tools and argument shapes. It uses specific verbs ('returns') and resources ('example questions'). It distinguishes itself from siblings like ask_pipeworx and discover_tools by being the onboarding entry point.

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

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

The description explicitly advises 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This provides clear guidance on when to use the tool, though it does not explicitly state when not to use it.

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

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

Discloses ownership enforcement and deactivation behavior beyond annotations. No contradictions.

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

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

Two sentences with no waste; each sentence adds essential information.

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

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

Sufficient for a simple tool: purpose, behavior, and link to historical data via recent_alerts.

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

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

Schema covers 100% of the single parameter; description adds no additional semantics beyond the schema's description.

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

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

Clear verb+resource: 'Cancel a subscription by id'. Distinguishes from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Explains ownership enforcement and that the row is deactivated, not deleted, providing usage context. No explicit when-not or alternatives.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses critical behavioral nuances: could_not_verify means the check did not happen and carries verification_error, and is NOT evidence for or against the claim; unsupported means no source found. It also explains the fast path for financial claims and the automatic fallback to the grounded pipeline, adding significant value.

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

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

The description is dense but well-organized: trigger phrases, usage context, routing logic, return values, and an important caller warning. Every sentence adds value, and the structure flows logically from what it does to how to interpret results. The length is justified by the complexity, and it avoids fluff.

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

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

Even without an output schema, the description explains return values (verdict options, actual value with citation, reasoning) and error semantics (verification_error, unsupported). It covers the tool's behavior across different claim types and clarifies potentially confusing statuses, making it complete for an agent to invoke and interpret results 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 covers both parameters with descriptions, but the description adds meaningful guidance: tolerance_pct overrides the implied tolerance, with recommended values (1-2 for hallucination detection) and default behavior (capped at 5). This goes beyond the schema's basic field descriptions and helps the agent use the parameter effectively.

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

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

The description explicitly states the tool's purpose: natural-language claim verification against authoritative sources, with specific trigger phrases like 'fact check' and 'verify the claim that'. It clearly distinguishes itself from siblings by focusing on claim verification and mentioning it replaces multiple sequential calls, making the purpose unambiguous.

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

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

It provides a clear 'use whenever' context: 'whenever the agent needs to check whether something a user said is factually correct.' It also explains routing for financial vs. other claims. However, it does not explicitly state when NOT to use it or name alternative tools, relying on overall tool set differentiation.

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